mirror/slate
1
0
Fork 0
mirror of https://github.com/ianstormtaylor/slate.git synced 2025-08-26 08:34:28 +02:00
Code Issues Releases Wiki Activity

Split API reference so each object has its own page

Browse Source
This commit is contained in:
Sunny Hirai
2021-03-29 00:02:43 -07:00
parent 2a8ba9c39b
commit 0ef080723f
12 changed files with 710 additions and 704 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/Summary.md
View File

@@ -28,9 +28,17 @@
## API ## API
- [Transforms](./api/transforms.md) - [Transforms](./api/transforms.md)
- [Nodes (Node, Editor, Element, Text)](./api/nodes.md) - [Node](./api/nodes.md)
- [Locations (Path, Point, Range)](./api/locations.md) - [Editor](./api/editor.md)
- [Refs (PointRef, RangeRef)](./api/refs.md) - [Element](./api/element.md)
- [Text](./api/text.md)
- [Location](./api/locations.md)
- [Path](./api/path.md)
- [Point](./api/point.md)
- [Range](./api/range.md)
- [Refs](./api/refs.md)
- [PointRef](./api/point-ref.md)
- [RangeRef](./api/range-ref.md)
- [Miscellaneous](./api/miscellaneous.md) - [Miscellaneous](./api/miscellaneous.md)
## Libraries ## Libraries

375
docs/api/editor.md Normal file
View File

@@ -0,0 +1,375 @@
# Editor
The `Editor` object stores all the state of a slate editor. It can be extended by plugins to add helpers and implement new behaviors.
```typescript
interface Editor {
children: Node[]
selection: Range | null
operations: Operation[]
marks: Record<string, any> | null
[key: string]: unknown
// Schema-specific node behaviors.
isInline: (element: Element) => boolean
isVoid: (element: Element) => boolean
normalizeNode: (entry: NodeEntry) => void
onChange: () => void
// Overrideable core actions.
addMark: (key: string, value: any) => void
apply: (operation: Operation) => void
deleteBackward: (unit: 'character' | 'word' | 'line' | 'block') => void
deleteForward: (unit: 'character' | 'word' | 'line' | 'block') => void
deleteFragment: () => void
insertBreak: () => void
insertFragment: (fragment: Node[]) => void
insertNode: (node: Node) => void
insertText: (text: string) => void
removeMark: (key: string) => void
}
```
## Static methods
###### `above<T extends Ancestor>(editor: Editor, options?): NodeEntry | undefined`
Get the ancestor above a location in the document.
Options: `{at?: Location, match?: NodeMatch, mode?: 'highest' | 'lowest', voids?: boolean}`
###### `addMark(editor: Editor, key: string, value: any): void`
Add a custom property to the leaf text nodes in the current selection.
If the selection is currently collapsed, the marks will be added to the
`editor.marks` property instead, and applied when text is inserted next.
###### `after(editor: Editor, at: Location, options?): Point | undefined`
Get the point after a location.
Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}`
###### `before(editor: Editor, at: Location, options?): Point | undefined`
Get the point before a location.
Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}`
###### `deleteBackward(editor: Editor, options?): void`
Delete content in the editor backward from the current selection.
Options: `{unit?: 'character' | 'word' | 'line' | 'block'}`
###### `deleteForward(editor: Editor, options?): void`
Delete content in the editor forward from the current selection.
Options: `{unit?: 'character' | 'word' | 'line' | 'block'}`
###### `deleteFragment(editor: Editor): void`
Delete the content in the current selection.
###### `edges(editor: Editor, at: Location): [Point, Point]`
Get the start and end points of a location.
###### `end(editor: Editor, at: Location): Point`
Get the end point of a location.
###### `first(editor: Editor, at: Location): NodeEntry`
Get the first node at a location.
###### `fragment(editor: Editor, at: Location): Descendant[]`
Get the fragment at a location.
###### `hasBlocks(editor: Editor, element: Element): boolean`
Check if a node has block children.
###### `hasInlines(editor: Editor, element: Element): boolean`
Check if a node has inline and text children.
###### `hasTexts(editor: Editor, element: Element): boolean`
Check if a node has text children.
###### `insertBreak(editor: Editor): void`
Insert a block break at the current selection.
###### `insertFragment(editor: Editor, fragment: Node[]): void`
Insert a fragment at the current selection.
If the selection is currently expanded, it will be deleted first.
###### `insertNode(editor: Editor, node: Node): void`
Insert a node at the current selection.
If the selection is currently expanded, it will be deleted first.
###### `insertText(editor: Editor, text: string): void`
Insert text at the current selection.
If the selection is currently expanded, it will be deleted first.
###### `isBlock(editor: Editor, value: any): value is Element`
Check if a value is a block `Element` object.
###### `isEditor(value: any): value is Editor`
Check if a value is an `Editor` object.
###### `isEnd(editor: Editor, point: Point, at: Location): boolean`
Check if a point is the end point of a location.
###### `isEdge(editor: Editor, point: Point, at: Location): boolean`
Check if a point is an edge of a location.
###### `isEmpty(editor: Editor, element: Element): boolean`
Check if an element is empty, accounting for void nodes.
###### `isInline(editor: Editor, value: any): value is Element`
Check if a value is an inline `Element` object.
###### `isNormalizing(editor: Editor): boolean`
Check if the editor is currently normalizing after each operation.
###### `isStart(editor: Editor, point: Point, at: Location): boolean`
Check if a point is the start point of a location.
###### `isVoid(editor: Editor, value: any): value is Element`
Check if a value is a void `Element` object.
###### `last(editor: Editor, at: Location): NodeEntry`
Get the last node at a location.
###### `leaf(editor: Editor, at: Location, options?): NodeEntry`
Get the leaf text node at a location.
Options: `{depth?: number, edge?: 'start' | 'end'}`
###### `levels<T extends Node>(editor: Editor, options?): Generator<NodeEntry, void, undefined>`
Iterate through all of the levels at a location.
Options: `{at?: Location, match?: NodeMatch, reverse?: boolean, voids?: boolean}`
###### `next<T extends Descendant>(editor: Editor, options?): NodeEntry<T> | undefined`
Get the matching node in the branch of the document after a location.
Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}`
###### `node(editor: Editor, at: Location, options?): NodeEntry`
Get the node at a location.
Options: `depth?: number, edge?: 'start' | 'end'`
###### `nodes(editor: Editor, options?): Generator<NodeEntry<T>, void, undefined>`
Iterate through all of the nodes in the Editor.
Options: `{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', universal?: boolean, reverse?: boolean, voids?: boolean}`
###### `normalize(editor: Editor, options?): void`
Normalize any dirty objects in the editor.
Options: `{force?: boolean}`
###### `parent(editor: Editor, at: Location, options?): NodeEntry<Ancestor>`
Get the parent node of a location.
Options: `{depth?: number, edge?: 'start' | 'end'}`
###### `path(editor: Editor, at: Location, options?): Path`
Get the path of a location.
Options: `{depth?: number, edge?: 'start' | 'end'}`
###### `pathRef(editor: Editor, path: Path, options?): PathRef`
Create a mutable ref for a `Path` object, which will stay in sync as new
operations are applied to the editor.
Options: `{affinity?: 'backward' | 'forward' | null}`
###### `pathRefs(editor: Editor): Set<PathRef>`
Get the set of currently tracked path refs of the editor.
###### `point(editor: Editor, at: Location, options?): Point`
Get the start or end point of a location.
Options: `{edge?: 'start' | 'end'}`
###### `pointRef(editor: Editor, point: Point, options?): PointRef`
Create a mutable ref for a `Point` object, which will stay in sync as new
operations are applied to the editor.
Options: `{affinity?: 'backward' | 'forward' | null}`
###### `pointRefs(editor: Editor): Set<PointRef>`
Get the set of currently tracked point refs of the editor.
###### `positions(editor: Editor, options?): Generator<Point, void, undefined>`
Iterate through all of the positions in the document where a `Point` can be
placed.
By default it will move forward by individual offsets at a time, but you
can pass the `unit: 'character'` option to moved forward one character, word,
or line at at time.
Note: By default void nodes are treated as a single point and iteration
will not happen inside their content unless you pass in true for the
voids option, then iteration will occur.
Options: `{at?: Location, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', reverse?: boolean, voids?: boolean}`
###### `previous(editor: Editor, options?): NodeEntry<T> | undefined`
Get the matching node in the branch of the document before a location.
Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}`
###### `range(editor: Editor, at: Location, to?: Location): Range`
Get a range of a location.
###### `rangeRef(editor: Editor, range: Range, options?): RangeRef`
Create a mutable ref for a `Range` object, which will stay in sync as new
operations are applied to the editor.
Options: `{affinity?: 'backward' | 'forward' | 'outward' | 'inward' | null}`
###### `rangeRefs(editor: Editor): Set<RangeRef>`
Get the set of currently tracked range refs of the editor.
###### `removeMark(editor: Editor, key: string): void`
Remove a custom property from all of the leaf text nodes in the current
selection.
If the selection is currently collapsed, the removal will be stored on
`editor.marks` and applied to the text inserted next.
###### `start(editor: Editor, at: Location): Point`
Get the start point of a location.
###### `string(editor: Editor, at: Location, options?): string`
Get the text string content of a location.
Note: by default the text of void nodes is considered to be an empty
string, regardless of content, unless you pass in true for the voids option
Options: : `{voids?: boolean}`
###### `unhangRange(editor: Editor, range: Range, options?): Range`
Convert a range into a non-hanging one.
Options: `{voids?: boolean}`
###### `void(editor: Editor, options?): NodeEntry<Element> | undefined`
Match a void node in the current branch of the editor.
Options: `{at?: Location, mode?: 'highest' | 'lowest', voids?: boolean}`
###### `withoutNormalizing(editor: Editor, fn: () => void): void`
Call a function, deferring normalization until after it completes.
### Instance methods
### Schema-specific methods to override
###### `isInline(element: Element)`
Check if a value is an inline `Element` object.
###### `isVoid(element: Element)`
Check if a value is a void `Element` object.
###### `normalizeNode(entry: NodeEntry)`
Normalize a Node according to the schema.
###### `onChange()`
Called when there is a change in the editor.
### Core actions
###### `addMark(key: string, value: any)`
Add a custom property to the leaf text nodes in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next.
###### `removeMark(key: string)`
Remove a custom property from the leaf text nodes in the current selection.
###### `deleteBackward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})`
Delete content in the editor backward from the current selection.
###### `deleteForward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})`
Delete content in the editor forward from the current selection.
###### `insertFragment(fragment: Node[])`
Insert a fragment at the current selection. If the selection is currently expanded, delete it first.
###### `deleteFragment()`
Delete the content of the current selection.
###### `insertBreak()`
Insert a block break at the current selection. If the selection is currently expanded, delete it first.
###### `insertNode(node: Node)`
Insert a node at the current selection. If the selection is currently expanded, delete it first.
###### `insertText(text: string)`
Insert text at the current selection. If the selection is currently expanded, delete it first.
###### `apply(operation: Operation)`
Apply an operation in the editor.

24
docs/api/element.md Normal file
View File

@@ -0,0 +1,24 @@
# Element
`Element` objects are a type of node in a Slate document that contain other `Element` nodes or `Text` nodes. They can be either "blocks" or "inlines" depending on the Slate editor's configuration.
```typescript
interface Element {
children: Node[]
[key: string]: unknown
}
```
## Static methods
###### `Element.isElement(value: any): value is Element`
Check if a `value` implements the `Element` interface.
###### `Element.isElementList(value: any): value is Element[]`
Check if a `value` is an array of `Element` objects.
###### `Element.matches(element: Element, props: Partial<Element>): boolean`
Check if an element matches a set of `props`. Note: This checks custom properties, but it does not ensure that any children are equivalent.

234
docs/api/locations.md
View File

@@ -6,238 +6,12 @@ The `Location` interface is a union of the ways to refer to a specific location
type Location = Path | Point | Range type Location = Path | Point | Range
``` ```
## Location - [Path](./api/path.md)
- [Point](./api/point.md)
- [Range](./api/range.md)
### Static methods ## Static methods
###### `Location.isLocation(value: any): value is Location` ###### `Location.isLocation(value: any): value is Location`
Check if a value implements the `Location` interface. Check if a value implements the `Location` interface.
## 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
###### `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.
###### `common(path: Path, another: Path): Path`
Get the common ancestor path of two paths.
###### `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.
###### `endsAfter(path: Path, another: Path): boolean`
Check if a path ends after one of the indexes in another.
###### `endsAt(path: Path, another: Path): boolean`
Check if a path ends at one of the indexes in another.
###### `endsBefore(path: Path, another: Path): boolean`
Check if a path ends before one of the indexes in another.
###### `equals(path: Path, another: Path): boolean`
Check if a path is exactly equal to another.
###### `hasPrevious(path: Path): boolean`
Check if the path of previous sibling node exists
###### `isAfter(path: Path, another: Path): boolean`
Check if a path is after another.
###### `isAncestor(path: Path, another: Path): boolean`
Check if a path is an ancestor of another.
###### `isBefore(path: Path, another: Path): boolean`
Check if a path is before another.
###### `isChild(path: Path, another: Path): boolean`
Check if a path is a child of another.
###### `isCommon(path: Path, another: Path): boolean`
Check if a path is equal to or an ancestor of another.
###### `isDescendant(path: Path, another: Path): boolean`
Check if a path is a descendant of another.
###### `isParent(path: Path, another: Path): boolean`
Check if a path is the parent of another.
###### `isPath(value: any): value is Path`
Check is a value implements the `Path` interface.
###### `isSibling(path: Path, another: Path): boolean`
Check if a path is a sibling of another.
###### `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}`
###### `next(path: Path): Path`
Given a path, get the path to the next sibling node.
###### `parent(path: Path): Path`
Given a path, return a new path referring to the parent node above it.
###### `previous(path: Path): Path`
Given a path, get the path to the previous sibling node.
###### `relative(path: Path, ancestor: Path): Path`
Get a path relative to an ancestor.
###### `transform(path: Path, operation: Operation, options?): Path | null`
Transform a path by an operation.
Options: `{ affinity?: 'forward' | 'backward' | null }`
## 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
[key: string]: unknown
}
```
### Static 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.
###### `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.
###### `Point.transform(point: Point, op: Operation, options?): Point | null`
Transform a `point` by an `op`.
Options: `{affinity?: 'forward' | 'backward' | null}`
## 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
[key: string]: unknown
}
```
### Static 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.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.intersection(range: Range, another: Range): Range | null`
Get the intersection of one `range` with `another`.
###### `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.
###### `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`
###### `Range.transform(range: Range, op: Operation, options): Range | null`
Transform a `range` by an `op`.
Options: `{affinity: 'forward' | 'backward' | 'outward' | 'inward' | null}`

440
docs/api/nodes.md
View File

@@ -1,4 +1,4 @@
# Nodes # Node
The `Node` union type represents all of the different types of nodes that occur in a Slate document tree. The `Node` union type represents all of the different types of nodes that occur in a Slate document tree.
@@ -9,9 +9,11 @@ type Descendant = Element | Text
type Ancestor = Editor | Element type Ancestor = Editor | Element
``` ```
## Node - [Editor](./api/editor.md)
- [Element](./api/element.md)
- [Text](./api/text.md)
### Static methods ## Static methods
###### `Node.ancestor(root: Node, path: Path): Ancestor` ###### `Node.ancestor(root: Node, path: Path): Ancestor`
@@ -114,435 +116,3 @@ Get the concatenated text string of a node's content. Note that this will not in
Return a generator of all leaf text nodes in a root node. Return a generator of all leaf text nodes in a root node.
Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}` Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}`
## Editor
The `Editor` object stores all the state of a slate editor. It can be extended by plugins to add helpers and implement new behaviors.
```typescript
interface Editor {
children: Node[]
selection: Range | null
operations: Operation[]
marks: Record<string, any> | null
[key: string]: unknown
// Schema-specific node behaviors.
isInline: (element: Element) => boolean
isVoid: (element: Element) => boolean
normalizeNode: (entry: NodeEntry) => void
onChange: () => void
// Overrideable core actions.
addMark: (key: string, value: any) => void
apply: (operation: Operation) => void
deleteBackward: (unit: 'character' | 'word' | 'line' | 'block') => void
deleteForward: (unit: 'character' | 'word' | 'line' | 'block') => void
deleteFragment: () => void
insertBreak: () => void
insertFragment: (fragment: Node[]) => void
insertNode: (node: Node) => void
insertText: (text: string) => void
removeMark: (key: string) => void
}
```
### Static methods
###### `above<T extends Ancestor>(editor: Editor, options?): NodeEntry | undefined`
Get the ancestor above a location in the document.
Options: `{at?: Location, match?: NodeMatch, mode?: 'highest' | 'lowest', voids?: boolean}`
###### `addMark(editor: Editor, key: string, value: any): void`
Add a custom property to the leaf text nodes in the current selection.
If the selection is currently collapsed, the marks will be added to the
`editor.marks` property instead, and applied when text is inserted next.
###### `after(editor: Editor, at: Location, options?): Point | undefined`
Get the point after a location.
Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}`
###### `before(editor: Editor, at: Location, options?): Point | undefined`
Get the point before a location.
Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}`
###### `deleteBackward(editor: Editor, options?): void`
Delete content in the editor backward from the current selection.
Options: `{unit?: 'character' | 'word' | 'line' | 'block'}`
###### `deleteForward(editor: Editor, options?): void`
Delete content in the editor forward from the current selection.
Options: `{unit?: 'character' | 'word' | 'line' | 'block'}`
###### `deleteFragment(editor: Editor): void`
Delete the content in the current selection.
###### `edges(editor: Editor, at: Location): [Point, Point]`
Get the start and end points of a location.
###### `end(editor: Editor, at: Location): Point`
Get the end point of a location.
###### `first(editor: Editor, at: Location): NodeEntry`
Get the first node at a location.
###### `fragment(editor: Editor, at: Location): Descendant[]`
Get the fragment at a location.
###### `hasBlocks(editor: Editor, element: Element): boolean`
Check if a node has block children.
###### `hasInlines(editor: Editor, element: Element): boolean`
Check if a node has inline and text children.
###### `hasTexts(editor: Editor, element: Element): boolean`
Check if a node has text children.
###### `insertBreak(editor: Editor): void`
Insert a block break at the current selection.
###### `insertFragment(editor: Editor, fragment: Node[]): void`
Insert a fragment at the current selection.
If the selection is currently expanded, it will be deleted first.
###### `insertNode(editor: Editor, node: Node): void`
Insert a node at the current selection.
If the selection is currently expanded, it will be deleted first.
###### `insertText(editor: Editor, text: string): void`
Insert text at the current selection.
If the selection is currently expanded, it will be deleted first.
###### `isBlock(editor: Editor, value: any): value is Element`
Check if a value is a block `Element` object.
###### `isEditor(value: any): value is Editor`
Check if a value is an `Editor` object.
###### `isEnd(editor: Editor, point: Point, at: Location): boolean`
Check if a point is the end point of a location.
###### `isEdge(editor: Editor, point: Point, at: Location): boolean`
Check if a point is an edge of a location.
###### `isEmpty(editor: Editor, element: Element): boolean`
Check if an element is empty, accounting for void nodes.
###### `isInline(editor: Editor, value: any): value is Element`
Check if a value is an inline `Element` object.
###### `isNormalizing(editor: Editor): boolean`
Check if the editor is currently normalizing after each operation.
###### `isStart(editor: Editor, point: Point, at: Location): boolean`
Check if a point is the start point of a location.
###### `isVoid(editor: Editor, value: any): value is Element`
Check if a value is a void `Element` object.
###### `last(editor: Editor, at: Location): NodeEntry`
Get the last node at a location.
###### `leaf(editor: Editor, at: Location, options?): NodeEntry`
Get the leaf text node at a location.
Options: `{depth?: number, edge?: 'start' | 'end'}`
###### `levels<T extends Node>(editor: Editor, options?): Generator<NodeEntry, void, undefined>`
Iterate through all of the levels at a location.
Options: `{at?: Location, match?: NodeMatch, reverse?: boolean, voids?: boolean}`
###### `next<T extends Descendant>(editor: Editor, options?): NodeEntry<T> | undefined`
Get the matching node in the branch of the document after a location.
Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}`
###### `node(editor: Editor, at: Location, options?): NodeEntry`
Get the node at a location.
Options: `depth?: number, edge?: 'start' | 'end'`
###### `nodes(editor: Editor, options?): Generator<NodeEntry<T>, void, undefined>`
Iterate through all of the nodes in the Editor.
Options: `{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', universal?: boolean, reverse?: boolean, voids?: boolean}`
###### `normalize(editor: Editor, options?): void`
Normalize any dirty objects in the editor.
Options: `{force?: boolean}`
###### `parent(editor: Editor, at: Location, options?): NodeEntry<Ancestor>`
Get the parent node of a location.
Options: `{depth?: number, edge?: 'start' | 'end'}`
###### `path(editor: Editor, at: Location, options?): Path`
Get the path of a location.
Options: `{depth?: number, edge?: 'start' | 'end'}`
###### `pathRef(editor: Editor, path: Path, options?): PathRef`
Create a mutable ref for a `Path` object, which will stay in sync as new
operations are applied to the editor.
Options: `{affinity?: 'backward' | 'forward' | null}`
###### `pathRefs(editor: Editor): Set<PathRef>`
Get the set of currently tracked path refs of the editor.
###### `point(editor: Editor, at: Location, options?): Point`
Get the start or end point of a location.
Options: `{edge?: 'start' | 'end'}`
###### `pointRef(editor: Editor, point: Point, options?): PointRef`
Create a mutable ref for a `Point` object, which will stay in sync as new
operations are applied to the editor.
Options: `{affinity?: 'backward' | 'forward' | null}`
###### `pointRefs(editor: Editor): Set<PointRef>`
Get the set of currently tracked point refs of the editor.
###### `positions(editor: Editor, options?): Generator<Point, void, undefined>`
Iterate through all of the positions in the document where a `Point` can be
placed.
By default it will move forward by individual offsets at a time, but you
can pass the `unit: 'character'` option to moved forward one character, word,
or line at at time.
Note: By default void nodes are treated as a single point and iteration
will not happen inside their content unless you pass in true for the
voids option, then iteration will occur.
Options: `{at?: Location, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', reverse?: boolean, voids?: boolean}`
###### `previous(editor: Editor, options?): NodeEntry<T> | undefined`
Get the matching node in the branch of the document before a location.
Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}`
###### `range(editor: Editor, at: Location, to?: Location): Range`
Get a range of a location.
###### `rangeRef(editor: Editor, range: Range, options?): RangeRef`
Create a mutable ref for a `Range` object, which will stay in sync as new
operations are applied to the editor.
Options: `{affinity?: 'backward' | 'forward' | 'outward' | 'inward' | null}`
###### `rangeRefs(editor: Editor): Set<RangeRef>`
Get the set of currently tracked range refs of the editor.
###### `removeMark(editor: Editor, key: string): void`
Remove a custom property from all of the leaf text nodes in the current
selection.
If the selection is currently collapsed, the removal will be stored on
`editor.marks` and applied to the text inserted next.
###### `start(editor: Editor, at: Location): Point`
Get the start point of a location.
###### `string(editor: Editor, at: Location, options?): string`
Get the text string content of a location.
Note: by default the text of void nodes is considered to be an empty
string, regardless of content, unless you pass in true for the voids option
Options: : `{voids?: boolean}`
###### `unhangRange(editor: Editor, range: Range, options?): Range`
Convert a range into a non-hanging one.
Options: `{voids?: boolean}`
###### `void(editor: Editor, options?): NodeEntry<Element> | undefined`
Match a void node in the current branch of the editor.
Options: `{at?: Location, mode?: 'highest' | 'lowest', voids?: boolean}`
###### `withoutNormalizing(editor: Editor, fn: () => void): void`
Call a function, deferring normalization until after it completes.
### Instance methods
#### Schema-specific methods to override
###### `isInline(element: Element)`
Check if a value is an inline `Element` object.
###### `isVoid(element: Element)`
Check if a value is a void `Element` object.
###### `normalizeNode(entry: NodeEntry)`
Normalize a Node according to the schema.
###### `onChange()`
Called when there is a change in the editor.
#### Core actions
###### `addMark(key: string, value: any)`
Add a custom property to the leaf text nodes in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next.
###### `removeMark(key: string)`
Remove a custom property from the leaf text nodes in the current selection.
###### `deleteBackward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})`
Delete content in the editor backward from the current selection.
###### `deleteForward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})`
Delete content in the editor forward from the current selection.
###### `insertFragment(fragment: Node[])`
Insert a fragment at the current selection. If the selection is currently expanded, delete it first.
###### `deleteFragment()`
Delete the content of the current selection.
###### `insertBreak()`
Insert a block break at the current selection. If the selection is currently expanded, delete it first.
###### `insertNode(node: Node)`
Insert a node at the current selection. If the selection is currently expanded, delete it first.
###### `insertText(text: string)`
Insert text at the current selection. If the selection is currently expanded, delete it first.
###### `apply(operation: Operation)`
Apply an operation in the editor.
## Element
`Element` objects are a type of node in a Slate document that contain other `Element` nodes or `Text` nodes. They can be either "blocks" or "inlines" depending on the Slate editor's configuration.
```typescript
interface Element {
children: Node[]
[key: string]: unknown
}
```
### Static methods
###### `Element.isElement(value: any): value is Element`
Check if a `value` implements the `Element` interface.
###### `Element.isElementList(value: any): value is Element[]`
Check if a `value` is an array of `Element` objects.
###### `Element.matches(element: Element, props: Partial<Element>): boolean`
Check if an element matches a set of `props`. Note: This checks custom properties, but it does not ensure that any children are equivalent.
## Text
`Text` objects represent the nodes that contain the actual text content of a Slate document along with any formatting properties. They are always leaf nodes in the document tree as they cannot contain any children.
```typescript
interface Text {
text: string
[key: string]: unknown
}
```
### Static methods
###### `Text.equals(text: Text, another: Text, options?): boolean`
Check if two text nodes are equal.
Options: `{loose?: boolean}`
###### `Text.isText(value: any): value is Text`
Check if a `value` implements the `Text` interface.
###### `Text.matches(text: Text, props: Partial<Text>): boolean`
Check if a `text` matches a set of `props`.
###### `Text.decorations(node: Text, decorations: Range[]): Text[]`
Get the leaves for a text node, given `decorations`.

116
docs/api/path.md Normal file
View File

@@ -0,0 +1,116 @@
# 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
###### `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.
###### `common(path: Path, another: Path): Path`
Get the common ancestor path of two paths.
###### `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.
###### `endsAfter(path: Path, another: Path): boolean`
Check if a path ends after one of the indexes in another.
###### `endsAt(path: Path, another: Path): boolean`
Check if a path ends at one of the indexes in another.
###### `endsBefore(path: Path, another: Path): boolean`
Check if a path ends before one of the indexes in another.
###### `equals(path: Path, another: Path): boolean`
Check if a path is exactly equal to another.
###### `hasPrevious(path: Path): boolean`
Check if the path of previous sibling node exists
###### `isAfter(path: Path, another: Path): boolean`
Check if a path is after another.
###### `isAncestor(path: Path, another: Path): boolean`
Check if a path is an ancestor of another.
###### `isBefore(path: Path, another: Path): boolean`
Check if a path is before another.
###### `isChild(path: Path, another: Path): boolean`
Check if a path is a child of another.
###### `isCommon(path: Path, another: Path): boolean`
Check if a path is equal to or an ancestor of another.
###### `isDescendant(path: Path, another: Path): boolean`
Check if a path is a descendant of another.
###### `isParent(path: Path, another: Path): boolean`
Check if a path is the parent of another.
###### `isPath(value: any): value is Path`
Check is a value implements the `Path` interface.
###### `isSibling(path: Path, another: Path): boolean`
Check if a path is a sibling of another.
###### `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}`
###### `next(path: Path): Path`
Given a path, get the path to the next sibling node.
###### `parent(path: Path): Path`
Given a path, return a new path referring to the parent node above it.
###### `previous(path: Path): Path`
Given a path, get the path to the previous sibling node.
###### `relative(path: Path, ancestor: Path): Path`
Get a path relative to an ancestor.
###### `transform(path: Path, operation: Operation, options?): Path | null`
Transform a path by an operation.
Options: `{ affinity?: 'forward' | 'backward' | null }`

17
docs/api/point-ref.md Normal file
View File

@@ -0,0 +1,17 @@
# 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
###### `PointRef.transform(ref: PointRef, op: Operation)`
Transform the point refs current value by an `op`.

39
docs/api/point.md Normal file
View File

@@ -0,0 +1,39 @@
# 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
[key: string]: unknown
}
```
## Static 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.
###### `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.
###### `Point.transform(point: Point, op: Operation, options?): Point | null`
Transform a `point` by an `op`.
Options: `{affinity?: 'forward' | 'backward' | null}`

17
docs/api/range-ref.md Normal file
View File

@@ -0,0 +1,17 @@
# 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
###### `RangeRef.transform(ref: RangeRef, op: Operation)`
Transform the range refs current value by an `op`.

69
docs/api/range.md Normal file
View File

@@ -0,0 +1,69 @@
# 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
[key: string]: unknown
}
```
## Static 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.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.intersection(range: Range, another: Range): Range | null`
Get the intersection of one `range` with `another`.
###### `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.
###### `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`
###### `Range.transform(range: Range, op: Operation, options): Range | null`
Transform a `range` by an `op`.
Options: `{affinity: 'forward' | 'backward' | 'outward' | 'inward' | null}`

39
docs/api/refs.md
View File

@@ -1,39 +1,6 @@
# Ref # Ref
`Ref` objects store up-to-date references to a `Point` or `Range` object in the document. `Ref` objects store up-to-date references to a `Point` or `Range` object in the document. They are named `PointRef` and `RangRef`.
## PointRef - [PointRef](./api/point-ref.md)
- [RangeRef](./api/range-ref.md)
`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
###### `PointRef.transform(ref: PointRef, op: Operation)`
Transform the point refs current value by an `op`.
## 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
###### `RangeRef.transform(ref: RangeRef, op: Operation)`
Transform the range refs current value by an `op`.

30
docs/api/text.md Normal file
View File

@@ -0,0 +1,30 @@
# Text
`Text` objects represent the nodes that contain the actual text content of a Slate document along with any formatting properties. They are always leaf nodes in the document tree as they cannot contain any children.
```typescript
interface Text {
text: string
[key: string]: unknown
}
```
## Static methods
###### `Text.equals(text: Text, another: Text, options?): boolean`
Check if two text nodes are equal.
Options: `{loose?: boolean}`
###### `Text.isText(value: any): value is Text`
Check if a `value` implements the `Text` interface.
###### `Text.matches(text: Text, props: Partial<Text>): boolean`
Check if a `text` matches a set of `props`.
###### `Text.decorations(node: Text, decorations: Range[]): Text[]`
Get the leaves for a text node, given `decorations`.