diff --git a/docs/Summary.md b/docs/Summary.md index 797ef14ea..4787f4d87 100644 --- a/docs/Summary.md +++ b/docs/Summary.md @@ -28,11 +28,13 @@ ## API - [Transforms](./api/transforms.md) -- [Node](./api/nodes.md) +- [Node Types](./api/nodes.md) + - [Node](./api/node.md) - [Editor](./api/editor.md) - [Element](./api/element.md) - [Text](./api/text.md) -- [Location](./api/locations.md) +- [Location Types](./api/locations.md) + - [Location](./api/location.md) - [Path](./api/path.md) - [Point](./api/point.md) - [Range](./api/range.md) diff --git a/docs/api/location.md b/docs/api/location.md new file mode 100644 index 000000000..2f49e9f7d --- /dev/null +++ b/docs/api/location.md @@ -0,0 +1,7 @@ +# Location + +## Static methods + +###### `Location.isLocation(value: any): value is Location` + +Check if a value implements the `Location` interface. diff --git a/docs/api/locations.md b/docs/api/locations.md index 2c2cf08fd..c96ac5db3 100644 --- a/docs/api/locations.md +++ b/docs/api/locations.md @@ -1,4 +1,4 @@ -# Location +# 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`. @@ -6,12 +6,7 @@ The `Location` interface is a union of the ways to refer to a specific location type Location = Path | Point | Range ``` +- [Location](./api/location.md) - [Path](./api/path.md) - [Point](./api/point.md) - [Range](./api/range.md) - -## Static methods - -###### `Location.isLocation(value: any): value is Location` - -Check if a value implements the `Location` interface. diff --git a/docs/api/node.md b/docs/api/node.md new file mode 100644 index 000000000..0cf85df9e --- /dev/null +++ b/docs/api/node.md @@ -0,0 +1,105 @@ +# Node + +## 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?): Generator>` + +Return a generator 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?): Generator>` + +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?): Generator>` + +Return a generator 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?): Generator` + +Return a generator 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?): Generator` + +Return a generator 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): boolean` + +Check if a node matches a set of `props`. + +###### `Node.nodes(root: Node, options?): Generator` + +Return a generator 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?): Generator>` + +Return a generator of all leaf text nodes in a root node. + +Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}` \ No newline at end of file diff --git a/docs/api/nodes.md b/docs/api/nodes.md index d14c57895..ac3a78dc5 100644 --- a/docs/api/nodes.md +++ b/docs/api/nodes.md @@ -1,4 +1,4 @@ -# Node +# Node Types The `Node` union type represents all of the different types of nodes that occur in a Slate document tree. @@ -9,110 +9,7 @@ type Descendant = Element | Text type Ancestor = Editor | Element ``` +- [Node](./api/node.md) - [Editor](./api/editor.md) - [Element](./api/element.md) - [Text](./api/text.md) - -## 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?): Generator>` - -Return a generator 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?): Generator>` - -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?): Generator>` - -Return a generator 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?): Generator` - -Return a generator 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?): Generator` - -Return a generator 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): boolean` - -Check if a node matches a set of `props`. - -###### `Node.nodes(root: Node, options?): Generator` - -Return a generator 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?): Generator>` - -Return a generator of all leaf text nodes in a root node. - -Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}`