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

Add API documentation for Slate core package (#3524)

Browse Source 
* Create transforms.md

* Create initial documentation for transforms

* Remove extra whitespace in transforms.md

* Create initial documentation for interfaces

* Rearrange API docs by category of interface

* Add documentation of static methods

* Use 'static' notation for transforms
This commit is contained in:
Cameron Ackerman
2020-03-05 09:30:29 -08:00
committed by GitHub
parent 1d9a7fa01d
commit 1e7d21f7cd
6 changed files with 590 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/Summary.md
View File

@@ -24,6 +24,14 @@
- [Normalizing](./concepts/10-normalizing.md)
- [Migrating](./concepts/XX-migrating.md)
## API
- [Transforms](./api/transforms.md)
- [Nodes](./api/nodes.md)
- [Locations](./api/locations.md)
- [Refs](./api/refs.md)
- [Miscellaneous](./api/miscellaneous.md)
## General
- [Resources](./general/resources.md)

130
docs/api/locations.md Normal file
View File

@@ -0,0 +1,130 @@
# 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.isLocation(value: any): value is Location`
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[]
```
## Point
`Point` objects refer to a specific location in a text node in a Slate document. Its `path` refers to the lcoation 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]: any
}
```
## 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]: any
}
```
###### `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): Iterable<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}`

9
docs/api/miscellaneous.md Normal file
View File

@@ -0,0 +1,9 @@
# Miscellaneous
## createEditor
`createEditor(): Editor` creates a new, empty `Editor` object.
## Operation
`Operation` objects define the low-level instructions that Slate editors use to apply changes to their internal state. Representing all changes as operations is what allows Slate editors to easily implement history, collaboration, and other features.

262
docs/api/nodes.md Normal file
View File

@@ -0,0 +1,262 @@
# Node
The `Node` union type represents all of the different types of nodes that occur in a Slate document tree.
```typescript
type Node = Editor | Element | Text
type Descendant = Element | Text
type Ancestor = Editor | Element
```
## Static methods
###### `Node.ancestor(root: Node, path: Path): Ancestor`
Get the node at a specific `path`, asserting that it is an ancestor node. If the specified node is not an ancestor node, throw an error.
###### `Node.ancestors(root: Node, path: Path, options?): Iterable<NodeEntry<Ancestor>>`
Return an iterable of all the ancestor nodes above a specific path. By default, the order is bottom-up, from lowest to highest ancestor in the tree, but you can pass the `reverse: true` option to go top-down.
Options: `{reverse?: boolean}`
###### `Node.child(root: Node, index: number): Descendant`
Get the child of a node at the specified `index`.
###### `Node.children(root: Node, path: Path, options?): Iterable<NodeEntry<Descendant>>`
Iterate over the children of a node at a specific path.
Options: `{reverse?: boolean}`
###### `Node.common(root: Node, path: Path, another: Path): NodeEntry`
Get an entry for the common ancestor node of two paths.
###### `Node.descendant(root: Node, path: Path): Descendant`
Get the node at a specific path, asserting that it's a descendant node.
###### `Node.descendants(root: Node, options?): Iterable<NodeEntry<Descendant>>`
Return an iterable of all the descendant node entries inside a root node. Each iteration will return a `NodeEntry` tuple consisting of `[Node, Path]`.
Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}`
###### `Node.elements(root: Node, options?): Iterable<ElementEntry>`
Return an iterable of all the element nodes inside a root node. Each iteration will return an `ElementEntry` tuple consisting of `[Element, Path]`. If the root node is an element, it will be included in the iteration as well.
Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}`
###### `Node.first(root: Node, path: Path): NodeEntry`
Get the first node entry in a root node from a `path`.
###### `Node.fragment(root: Node, range: Range): Descendant[]`
Get the sliced fragment represented by the `range`.
###### `Node.get(root: Node, path: Path): Node`
Get the descendant node referred to by a specific `path`. If the path is an empty array, get the root node itself.
###### `Node.has(root: Node, path: Path): boolean`
Check if a descendant node exists at a specific `path`.
###### `Node.isNode(value: any): value is Node`
Check if a `value` implements the `Node` interface.
###### `Node.isNodeList(value: any): value is Node[]`
Check if a `value` is a list of `Node` objects.
###### `Node.last(root: Node, path: Path): NodeEntry`
Get the last node entry in a root node at a specific `path`.
###### `Node.leaf(root: Node, path: Path): Text`
Get the node at a specific `path`, ensuring it's a leaf text node. If the node is not a leaf text node, throw an error.
###### `Node.levels(root: Node, path: Path, options?): Iterable<NodeEntry>`
Return an iterable of the nodes in a branch of the tree, from a specific `path`. By default, the order is top-down, from the lowest to the highest node in the tree, but you can pass the `reverse: true` option to go bottom-up.
Options: `{reverse?: boolean}`
###### `Node.matches(root: Node, props: Partial<Node>): boolean`
Check if a node matches a set of `props`.
###### `Node.nodes(root: Node, options?): Iterable<NodeEntry>`
Return an iterable of all the node entries of a root node. Each entry is returned as a `[Node, Path]` tuple, with the path referring to the node's position inside the root node.
Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}`
###### `Node.parent(root: Node, path: Path): Ancestor`
Get the parent of a node at a specific `path`.
###### `Node.string(root: Node): string`
Get the concatenated text string of a node's content. Note that this will not include spaces or line breaks between block nodes. This is not intended as a user-facing string, but as a string for performing offset-related computations for a node.
###### `Node.texts(root: Node, options?): Iterable<NodeEntry<Text>>`
Return an iterable of all leaf text nodes in a root node.
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]: any
// 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
}
```
### Instance methods
#### Schema-specific actions
###### `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()`
#### 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]: any
}
```
### 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]: any
}
```
### 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`.

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

@@ -0,0 +1,39 @@
# Ref
`Ref` objects store up-to-date references to a `Point` or `Range` object in the document.
## 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`.
## 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`.

142
docs/api/transforms.md Normal file
View File

@@ -0,0 +1,142 @@
# Transforms
Transforms are helper functions operating on the document. They can be used in defining your own commands.
## Node transforms
Transforms that operate on nodes.
###### NodeOptions
All transforms listed below support a parameter `options`. This includes options specific to the transform, and general `NodeOptions` to specify the place in the document that the transform is applied to.
```typescript
interface NodeOptions {
at?: Location
match?: (node: Node) => boolean
mode?: 'highest' | 'lowest'
voids?: boolean
}
```
###### `Transforms.insertNodes(editor: Editor, nodes: Node | Node[], options?)`
Insert `nodes` at the specified location in the document. If no location is specified, insert at the current selection. If there is no selection, insert at the end of the document.
Options supported: `NodeOptions & {hanging?: boolean, select?: boolean}`.
###### `Transforms.removeNodes(editor: Editor, options?)`
Remove nodes at the specified location in the document. If no location is specified, remove the nodes in the selection.
Options supported: `NodeOptions & {hanging?: boolean}`
###### `Transforms.mergeNodes(editor: Editor, options?)`
Merge a node at the specified location with the previous node at the same depth. If no location is specified, use the selection. Resulting empty container nodes are removed.
Options supported: `NodeOptions & {hanging?: boolean}`
###### `Transforms.splitNodes(editor: Editor, options?)`
Split nodes at the specified location. If no location is specified, split the selection.
Options supported: `NodeOptions & {height?: number, always?: boolean}`
###### `Transforms.wrapNodes(editor: Editor, element: Element, options?)`
Wrap nodes at the specified location in the `element` container. If no location is specified, wrap the selection.
Options supported: `NodeOptions & {split?: boolean}`. For `options.mode`, `'all'` is also supported.
###### `Transforms.unwrapNodes(editor: Editor, options?)`
Unwrap nodes at the specified location. If necessary, the parent node is split. If no location is specified, use the selection.
Options supported: `NodeOptions & {split?: boolean}`. For `options.mode`, `'all'` is also supported.
###### `Transforms.setNodes(editor: Editor, props: Partial<Node>, options?)`
Set properties of nodes at the specified location. If no location is specified, use the selection.
Options supported: `NodeOptions & {hanging?: boolean, split?: boolean}`. For `options.mode`, `'all'` is also supported.
###### `Transforms.unsetNodes(editor: Editor, props: string | string[], options?)`
Unset properties of nodes at the specified location. If no location is specified, use the selection.
Options supported: `NodeOptions & {split?: boolean}`. For `options.mode`, `'all'` is also supported.
###### `Transforms.liftNodes(editor: Editor, options?)`
Lift nodes at the specified location upwards in the document tree. If necessary, the parent node is split. If no location is specified, use the selection.
Options supported: `NodeOptions`. For `options.mode`, `'all'` is also supported.
###### `Transforms.moveNodes(editor: Editor, options)`
Move the nodes from an origin to a destination. A destination must be specified in the `options`. If no origin is specified, move the selection.
Options supported: `NodeOptions & {to: Path}`. For `options.mode`, `'all'` is also supported.
## Selection transforms
Transforms that operate on the document's selection.
###### `Transforms.collapse(editor: Editor, options?)`
Collapse the selection to a single point.
Options: `{edge?: 'anchor' | 'focus' | 'start' | 'end'}`
###### `Transforms.select(editor: Editor, target: Location)`
Set the selection to a new value specified by `target`.
###### `Transforms.deselect(editor: Editor)`
Unset the selection.
###### `Transforms.move(editor: Editor, options?)`
Move the selection's point forward or backward.
Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line', reverse?: boolean, edge?: 'anchor' | 'focus' | 'start' | 'end'}`
###### `Transforms.setPoint(editor: Editor, props: Partial<Point>, options?)`
Set new properties on one of the selection's points.
Options: `{edge?: 'anchor' | 'focus' | 'start' | 'end'}`
###### `Transforms.setSelection(editor: Editor, props: Partial<Range>)`
Set new properties on the selection.
## Text transforms
Transforms that operate on text.
###### `Transforms.delete(editor: Editor, options?)`
Delete text in the document.
Options: `{at?: Location, distance?: number, unit?: 'character' | 'word' | 'line' | 'block', reverse?: boolean, hanging?: boolean, voids?: boolean}`
###### `Transforms.insertFragment(editor: Editor, fragment: Node[], options?)`
Insert of fragment of nodes at the specified location in the document. If no location is specified, insert at the current selection.
Options: `{at?: Location, hanging?: boolean, voids?: boolean}`
###### `Transforms.insertText(editor: Editor, text: string, options?)`
Insert a string of text at the specified location in the document. If no location is specified, insert at the current selection.
Options: `{at?: Location, voids?: boolean}`
## General transform
###### `Transforms.transform(editor: Editor, transform: Transform)`
Transform the `editor` by an `operation`.