From f8946fb876b04f9f8cf2d61ece49f5394f777a04 Mon Sep 17 00:00:00 2001 From: Ian Storm Taylor Date: Tue, 12 Jul 2016 17:54:11 -0700 Subject: [PATCH] add more reference docs --- Readme.md | 16 ++++---- docs/reference/models/block.md | 20 +++++++++- docs/reference/models/character.md | 50 ++++++++++++++++++++++++ docs/reference/models/data.md | 21 ++++++++++ docs/reference/models/document.md | 12 +++++- docs/reference/models/inline.md | 20 +++++++++- docs/reference/models/mark.md | 48 +++++++++++++++++++++++ docs/reference/models/text.md | 63 ++++++++++++++++++++++++++++++ 8 files changed, 237 insertions(+), 13 deletions(-) create mode 100644 docs/reference/models/character.md create mode 100644 docs/reference/models/data.md create mode 100644 docs/reference/models/mark.md create mode 100644 docs/reference/models/text.md diff --git a/Readme.md b/Readme.md index caf2afdbe..0f51f0333 100644 --- a/Readme.md +++ b/Readme.md @@ -82,16 +82,16 @@ If you're using Slate for the first time, check out the [Getting Started](./docs - [Editor](docs/reference/components/editor.md) - [Placeholder](docs/reference/components/placeholder.md) - Models - - Block - - Character - - Data - - Document - - Inline - - Mark - - Node + - [Block](docs/reference/models/block.md) + - [Character](docs/reference/models/character.md) + - [Data](docs/reference/data.md) + - [Document](docs/reference/models/document.md) + - [Inline](docs/reference/models/inline.md) + - [Mark](docs/reference/mark.md) + - [Node](docs/reference/models/node.md) - [Selection](docs/reference/models/selection.md) - State - - Text + - [Text](docs/reference/text.md) - Transform - Plugins - [Plugins](docs/reference/plugins/plugins.md) diff --git a/docs/reference/models/block.md b/docs/reference/models/block.md index fc2617930..c548f058c 100644 --- a/docs/reference/models/block.md +++ b/docs/reference/models/block.md @@ -19,6 +19,9 @@ Block nodes may contain nested block nodes, inline nodes, and text nodes—just - [`kind`](#kind) - [`length`](#length) - [`text`](#text) +- [Static Methods](#static-methods) + - [`Block.create`](#block-create) + - [`Block.createList`](#block-createlist) - [Node Methods](#node-methods) @@ -26,10 +29,10 @@ Block nodes may contain nested block nodes, inline nodes, and text nodes—just ```js Block({ - data: Immutable.Map, + data: Data, isVoid: Boolean, key: String, - nodes: Immutable.List, + nodes: Immutable.List, type: String }) ``` @@ -80,6 +83,19 @@ The sum of the lengths of all of the descendant [`Text`](./text.md) nodes of thi A concatenated string of all of the descendant [`Text`](./text.md) nodes of this node. +## Static Methods + +### `Block.create` +`Block.create(properties: Object) => Block` + +Create a block from a plain Javascript object of `properties`. + +### `Block.createList` +`Block.createList(array: Array) => List` + +Create a list of block nodes from a plain Javascript `array`. + + ## Node Methods Blocks implement the [`Node`](./node.md) interface. For information about their methods, see the [`Node` reference](./node.md). diff --git a/docs/reference/models/character.md b/docs/reference/models/character.md new file mode 100644 index 000000000..a9280f0e8 --- /dev/null +++ b/docs/reference/models/character.md @@ -0,0 +1,50 @@ + +# `Character` + +```js +import { Character } from 'slate' +``` + +A character in a [`Text`](./text.md) node. + +Characters are how Slate associates [`Marks`](./mark.md) with a range of text, for formatting. + +- [Properties](#properties) + - [`marks`](#marks) + - [`text`](#text) +- [Static Methods](#static-methods) + - [`Character.create`](#character-create) + - [`Character.createList`](#character-createlist) + + +## Properties + +```js +Character({ + marks: Immutable.Set, + text: String +}) +``` + +### `marks` +`Immutable.Set` + +A set of [`Marks`](./mark.md) attached to the character. + +### `text` +`String` + +The text string of the character. + + +## Static Methods + +### `Character.create` +`Character.create(properties: Object) => Character` + +Create a character from a plain Javascript object of `properties`. + +### `Character.createList` +`Character.createList(array: Array) => List` + +Create a list of characters from a plain Javascript `array`. diff --git a/docs/reference/models/data.md b/docs/reference/models/data.md new file mode 100644 index 000000000..a13b7f04d --- /dev/null +++ b/docs/reference/models/data.md @@ -0,0 +1,21 @@ + +# `Data` + +```js +import { Data } from 'slate' +``` + +Data is simply a thin wrapper around [`Immutable.Map`](https://facebook.github.io/immutable-js/docs/#/Map), so that you don't need to ever depend on Immutable directly, and for future compatibility. + +A data object can have any properties associated with it. + +- [Static Methods](#static-methods) + - [`Data.create`](#data-create) + + +## Static Methods + +### `Data.create` +`Data.create(properties: Object) => Data` + +Create a data object from a plain Javascript object of `properties`. diff --git a/docs/reference/models/document.md b/docs/reference/models/document.md index 705c6052d..79eff5759 100644 --- a/docs/reference/models/document.md +++ b/docs/reference/models/document.md @@ -15,6 +15,8 @@ Documents are made up of block nodes, inline nodes, and text nodes—just like i - [`kind`](#kind) - [`length`](#length) - [`text`](#text) +- [Static Methods](#static-methods) + - [`Document.create`](#document-create) - [Node Methods](#node-methods) @@ -22,7 +24,7 @@ Documents are made up of block nodes, inline nodes, and text nodes—just like i ```js Document({ - nodes: Immutable.List, + nodes: Immutable.List, }) ``` @@ -50,6 +52,14 @@ The sum of the lengths of all of the descendant [`Text`](./text.md) nodes of thi A concatenated string of all of the descendant [`Text`](./text.md) nodes of this node. +## Static Methods + +### `Document.create` +`Document.create(properties: Object) => Document` + +Create a block from a plain Javascript object of `properties`. + + ## 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 index f1210c191..0be91ef84 100644 --- a/docs/reference/models/inline.md +++ b/docs/reference/models/inline.md @@ -19,6 +19,9 @@ Inline nodes may contain nested inline nodes and text nodes—just like in the D - [`kind`](#kind) - [`length`](#length) - [`text`](#text) +- [Static Methods](#static-methods) + - [`Inline.create`](#inline-create) + - [`Inline.createList`](#inline-createlist) - [Node Methods](#node-methods) @@ -26,10 +29,10 @@ Inline nodes may contain nested inline nodes and text nodes—just like in the D ```js Inline({ - data: Immutable.Map, + data: Data, isVoid: Boolean, key: String, - nodes: Immutable.List, + nodes: Immutable.List, type: String }) ``` @@ -80,6 +83,19 @@ The sum of the lengths of all of the descendant [`Text`](./text.md) nodes of thi A concatenated string of all of the descendant [`Text`](./text.md) nodes of this node. +## Static Methods + +### `Block.create` +`Block.create(properties: Object) => Block` + +Create a block from a plain Javascript object of `properties`. + +### `Block.createList` +`Block.createList(array: Array) => List` + +Create a list of block nodes from a plain Javascript `array`. + + ## 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/mark.md b/docs/reference/models/mark.md new file mode 100644 index 000000000..adec2f463 --- /dev/null +++ b/docs/reference/models/mark.md @@ -0,0 +1,48 @@ + +# `Mark` + +```js +import { Mark } from 'slate' +``` + +A formatting mark that can be associated with [`Characters`](./character.md). Marks are how Slate represents rich formatting like **bold** or _italic_. + +- [Properties](#properties) + - [`data`](#data) + - [`type`](#type) +- [Static Methods](#static-methods) + - [`Mark.create`](#mark-create) + - [`Mark.createSet`](#mark-createset) + + +## Properties + +```js +Mark({ + data: Data, + type: String +}) +``` + +### `data` +`Data` + +A map of [`Data`](./data.md). + +### `type` +`String` + +The custom type of the mark (eg. `bold` or `italic`). + + +## Static Methods + +### `Mark.create` +`Mark.create(properties: Object) => Mark` + +Create a mark from a plain Javascript object of `properties`. + +### `Mark.createSet` +`Mark.createSet(array: Array) => Set` + +Create a set of marks from a plain Javascript `array`. diff --git a/docs/reference/models/text.md b/docs/reference/models/text.md new file mode 100644 index 000000000..a12afbbd7 --- /dev/null +++ b/docs/reference/models/text.md @@ -0,0 +1,63 @@ + +# `Text` + +```js +import { Text } from 'slate' +``` + +A text node in a Slate [`Document`](./document.md). Text nodes are always the bottom-most leaves in the document, just like in the DOM. + +- [Properties](#properties) + - [`characters`](#characters) + - [`key`](#key) +- [Computed Properties](#computed-properties) + - [`kind`](#kind) + - [`length`](#length) + - [`text`](#text) +- [Static Methods](#static-methods) + - [`Text.create`](#text-create) + + +## Properties + +```js +Text({ + characters: Immutable.List, + key: String +}) +``` + +### `characters` + +A list of [`Characters`](./character.md) with associated [`Marks`](./mark.md) that make up the text node's content. + +### `key` +`String` + +A unique identifier for the node. + + +## Computed Properties + +### `kind` +`String` + +An immutable string value of `'text'` for easily separating this node from [`Inline`](./inline.md) or [`Block`](./block.md) nodes. + +### `length` +`Number` + +The length of all of the characters in the text node. + +### `text` +`String` + +A concatenated string of all of the characters in the text node. + + +## Static Methods + +### `Text.create` +`Text.create(properties: Object) => Text` + +Create a text from a plain Javascript object of `properties`.