diff --git a/docs/reference/models/block.md b/docs/reference/models/block.md index 0b0ff19cb..fc2617930 100644 --- a/docs/reference/models/block.md +++ b/docs/reference/models/block.md @@ -5,9 +5,9 @@ import { Block } from 'slate' ``` -A block node in a Slate [`Document`](./document.md). +A block node in a Slate [`Document`](./document.md). Block nodes implement the [`Node`](./node.md) interface. -Block nodes can contained nested block nodes, inline nodes, and text nodes—just like in the DOM. They always contain at least one text node child. +Block nodes may contain nested block nodes, inline nodes, and text nodes—just like in the DOM. They always contain at least one text node child. - [Properties](#properties) - [`data`](#data) @@ -21,6 +21,7 @@ Block nodes can contained nested block nodes, inline nodes, and text nodes—jus - [`text`](#text) - [Node Methods](#node-methods) + ## Properties ```js @@ -36,14 +37,14 @@ Block({ ### `data` `Immutable.Map` -Arbitrary data associated with the block. Defaults to an empty `Map`. +Arbitrary data associated with the node. Defaults to an empty `Map`. ### `isVoid` `Boolean` Whether the node is a "void" node, meaning that it has no child content (eg. images, videos, etc.). Defaults to `false`. -Note that even though a node may be "void", it will still contain a single, empty [`Text`](./text.md) node for consistency across other operations. However, when rendered by Slate that single text node will not be visible. +Note that even though a node may be "void", it will still contain a single, empty [`Text`](./text.md) node for consistency across other operations. However, when rendered by Slate that single [`Text`](./text.md) node will not be visible. ### `key` `String` @@ -58,7 +59,7 @@ A list of child nodes. Defaults to a list with a single text node child. ### `type` `String` -The custom type of the block (eg. `blockquote` or `list-item`). +The custom type of the node (eg. `blockquote` or `list-item`). ## Computed Properties @@ -66,7 +67,7 @@ The custom type of the block (eg. `blockquote` or `list-item`). ### `kind` `String` -An immutable string value of `'block'` for easily separating this node from inline or text nodes. +An immutable string value of `'block'` for easily separating this node from [`Inline`](./inline.md) or [`Text`](./text.md) nodes. ### `length` `Number` diff --git a/docs/reference/models/document.md b/docs/reference/models/document.md new file mode 100644 index 000000000..705c6052d --- /dev/null +++ b/docs/reference/models/document.md @@ -0,0 +1,55 @@ + +# `Document` + +```js +import { Document } from 'slate' +``` + +The top-level node in Slate. + +Documents are made up of block nodes, inline nodes, and text nodes—just like in the DOM. + +- [Properties](#properties) + - [`nodes`](#nodes) +- [Computed Properties](#computed-properties) + - [`kind`](#kind) + - [`length`](#length) + - [`text`](#text) +- [Node Methods](#node-methods) + + +## Properties + +```js +Document({ + nodes: Immutable.List, +}) +``` + +### `nodes` +`Immutable.List` + +A list of child nodes. + + +## Computed Properties + +### `kind` +`String` + +An immutable string value of `'document'` for easily separating this node from [`Block`](./block.dm), [`Inline`](./inline.md) or [`Text`](./text.md) nodes. + +### `length` +`Number` + +The sum of the lengths of all of the descendant [`Text`](./text.md) nodes of this node. + +### `text` +`String` + +A concatenated string of all of the descendant [`Text`](./text.md) nodes of this node. + + +## Node Methods + +Documents implement the [`Node`](./node.md) interface. For information about their methods, see the [`Node` reference](./node.md). diff --git a/docs/reference/models/inline.md b/docs/reference/models/inline.md new file mode 100644 index 000000000..f1210c191 --- /dev/null +++ b/docs/reference/models/inline.md @@ -0,0 +1,85 @@ + +# `Inline` + +```js +import { Inline } from 'slate' +``` + +A inline node in a Slate [`Document`](./document.md). Inline nodes implement the [`Node`](./node.md) interface. + +Inline nodes may contain nested inline nodes and text nodes—just like in the DOM. They always contain at least one text node child. + +- [Properties](#properties) + - [`data`](#data) + - [`isVoid`](#isvoid) + - [`key`](#key) + - [`nodes`](#nodes) + - [`type`](#type) +- [Computed Properties](#computed-properties) + - [`kind`](#kind) + - [`length`](#length) + - [`text`](#text) +- [Node Methods](#node-methods) + + +## Properties + +```js +Inline({ + data: Immutable.Map, + isVoid: Boolean, + key: String, + nodes: Immutable.List, + type: String +}) +``` + +### `data` +`Immutable.Map` + +Arbitrary data associated with the node. Defaults to an empty `Map`. + +### `isVoid` +`Boolean` + +Whether the node is a "void" node, meaning that it has no child content (eg. emoji, icons, etc.). Defaults to `false`. + +Note that even though a node may be "void", it will still contain a single, empty [`Text`](./text.md) node for consistency across other operations. However, when rendered by Slate that single [`Text`](./text.md) node will not be visible. + +### `key` +`String` + +A unique identifier for the node. + +### `nodes` +`Immutable.List` + +A list of child nodes. Defaults to a list with a single text node child. + +### `type` +`String` + +The custom type of the node (eg. `link` or `hashtag`). + + +## Computed Properties + +### `kind` +`String` + +An immutable string value of `'inline'` for easily separating this node from [`Block`](./block.md) or [`Text`](./text.md) nodes. + +### `length` +`Number` + +The sum of the lengths of all of the descendant [`Text`](./text.md) nodes of this node. + +### `text` +`String` + +A concatenated string of all of the descendant [`Text`](./text.md) nodes of this node. + + +## Node Methods + +Inlines implement the [`Node`](./node.md) interface. For information about their methods, see the [`Node` reference](./node.md). diff --git a/docs/reference/models/node.md b/docs/reference/models/node.md new file mode 100644 index 000000000..aa74b2cdf --- /dev/null +++ b/docs/reference/models/node.md @@ -0,0 +1,215 @@ + +# `Node` + +`Node` is not a publicly accessible module, but instead an interface that [`Document`](./document.md), [`Block`](./block.md) and [`Inline`](./inline.md) all implement. + +- [Properties](#properties) + - [`nodes`](#nodes) +- [Computed Properties](#computed-properties) + - [`kind`](#kind) + - [`length`](#length) + - [`text`](#text) +- [Retrieval Methods](#retrieval-methods) + - [`filterDescendants`](#filterdescendants) + - [`findDescendant`](#finddescendant) + - [`getBlocksAtRange`](#getblockatrange) + - [`getBlocks`](#getblocks) + - [`getCharactersAtRange`](#getcharactersatrange) + - [`getChild`](#getchild) + - [`getClosestBlock`](#getclosestblock) + - [`getClosestInline`](#getclosestinline) + - [`getClosest`](#getclosest) + - [`getDepth`](#getdepth) + - [`getDescendant`](#getdescendant) + - [`getFragmentAtRange`](#getfragmentatrange) + - [`getInlinesAtRange`](#getinlinesatrange) + - [`getMarksAtRange`](#getmarksatrange) + - [`getNextBlock`](#getnextblock) + - [`getNextSibling`](#getnextsibling) + - [`getNextText`](#getnexttext) + - [`getParent`](#parent) + - [`getPreviousBlock`](#getpreviousblock) + - [`getPreviousSibling`](#getprevioussibling) + - [`getPreviousText`](#getprevioustext) + - [`getTextAtOffset`](#gettextatoffset) + - [`getTextsAtRange`](#gettextsatrange) + - [`hasChild`](#haschild) + - [`hasDescendant`](#hasdescendant) +- [Transform Methods](#transform-methods) + - [`mapDescendants`](#mapdescendants) + - [`removeDescendant`](#removedescendant) + - [`updateDescendant`](#updatedescendant) + + +## Properties + +### `nodes` +`Immutable.List` + +A list of child nodes. Defaults to a list with a single text node child. + + +## Computed Properties + +### `kind` +`String` + +An immutable string value of `'block'` for easily separating this node from [`Inline`](./inline.md) or [`Text`](./text.md) nodes. + +### `length` +`Number` + +The sum of the lengths of all of the descendant [`Text`](./text.md) nodes of this node. + +### `text` +`String` + +A concatenated string of all of the descendant [`Text`](./text.md) nodes of this node. + + +## Retrieval Methods + +### `filterDescendants` +`filterDescendants(iterator: Function) => List` + +Deeply filter the descendant nodes of a node by `iterator`. + +### `findDescendant` +`findDescendant(iterator: Function) => Node || Void` + +Deeply find a descendant node by `iterator`. + +### `getBlocksAtRange` +`getBlocksAtRange(range: Selection) => List` + +Get all of the bottom-most [`Block`](./block.md) nodes in a `range`. + +### `getBlocks` +`getBlocks() => List` + +Get all of the bottom-most [`Block`](./block.md) node descendants. + +### `getCharactersAtRange` +`getCharactersAtRange(range: Selection) => List` + +Get a list of all of the [`Charaters`](./character.md) in a `range`. + +### `getChild` +`getChild(key: Key || Node) => Node || Void` + +Get a child by `key`. + +### `getClosestBlock` +`getClosestBlock(key: String || Node) => Node || Void` + +Get the closest [`Block`](./block.md) node to a descendant node by `key`. + +### `getClosestInline` +`getClosestInline(key: String || Node) => Node || Void` + +Get the closest [`Inline`](./inline.md) node to a descendant node by `key`. + +### `getClosest` +`getClosest(key: String || Node, match: Function) => Node || Void` + +Get the closest parent node of a descendant node by `key` that matches a `match` function. + +### `getDepth` +`getDepth(key: String || Node) => Number` + +Get the depth of a descendant node by `key`. + +### `getDescendant` +`getDescendant(key: String || Node) => Node || Void` + +Get a descendant node by `key`. + +### `getFragmentAtRange` +`getFragmentAtRange(range: Selection) => Document` + +Get a document fragment of the nodes in a `range`. + +### `getInlinesAtRange` +`getInlinesAtRange(range: Selection) => List` + +Get all of the top-most [`Inline`](./inline.md) nodes in a `range`. + +### `getMarksAtRange` +`getMarksAtRange(range: Selection) => Set` + +Get a set of all of the marks in a `range`. + +### `getNextBlock` +`getNextBlock(key: String || Node) => Node || Void` + +Get the next, bottom-most [`Block`](./block.md) node after a descendant by `key`. + +### `getNextSibling` +`getNextSibling(key: String || Node) => Node || Void` + +Get the next sibling of a descendant by `key`. + +### `getNextText` +`getNextText(key: String || Node) => Node || Void` + +Get the next [`Text`](./text.md) node after a descendant by `key`. + +### `getParent` +`getParent(key: String || Node) => Node || Void` + +Get the parent node of a descendant by `key`. + +### `getPreviousBlock` +`getPreviousBlock(key: String || Node) => Node || Void` + +Get the previous, bottom-most [`Block`](./block.md) node before a descendant by `key`. + +### `getPreviousSibling` +`getPreviousSibling(key: String || Node) => Node || Void` + +Get the previous sibling of a descendant by `key`. + +### `getPreviousText` +`getPreviousText(key: String || Node) => Node || Void` + +Get the previous [`Text`](./text.md) node before a descendant by `key`. + +### `getTextAtOffset` +`getTextAtOffset(offset: Number) => Text || Void` + +Get the [`Text`](./text.md) node at an `offset`. + +### `getTextsAtRange` +`getTextsAtRange(range: Selection) => List` + +Get all of the [`Text`](./text.md) nodes in a `range`. + +### `hasChild` +`hasChild(key: String || Node) => Boolean` + +Check whether the node has a child node by `key`. + +### `hasDescendant` +`hasDescendant(key: String || Node) => Boolean` + +Check whether the node has a descendant node by `key`. + + +## Transform Methods + +Since nodes are immutable, all of the transform methods return a new copy of the node in question. + +### `mapDescendants` +`mapDescendants(iterator: Function) => Node` + +Map all of the descendant nodes of a node through an `iterator` function. + +### `removeDescendant` +`removeDescendant(key: String || Node) => Node` + +Remove a descendant node from the tree by `key`. + +### `updateDescendant` +`updateDescendant(node: Node) => Node` + +Update a descendant `node` to the new value. diff --git a/lib/models/inline.js b/lib/models/inline.js index 500f463ae..131e96e05 100644 --- a/lib/models/inline.js +++ b/lib/models/inline.js @@ -53,8 +53,7 @@ class Inline extends new Record(DEFAULTS) { properties.isVoid = !!properties.isVoid properties.nodes = Inline.createList(properties.nodes) - let inline = new Inline(properties) - return inline.normalize() + return new Inline(properties).normalize() } /**