slate-edit-list/NewAPI.md

A Slate plugin to handle keyboard events in lists.

# slate-edit-list

[![NPM version](https://badge.fury.io/js/slate-edit-list.svg)](http://badge.fury.io/js/slate-edit-list)
[![Linux Build Status](https://travis-ci.org/GitbookIO/slate-edit-list.png?branch=master)](https://travis-ci.org/GitbookIO/slate-edit-list)

A Slate plugin to handle keyboard events in lists. List items can contain blocks.

### Install

```
npm install slate-edit-list
```

### Features

Natural keybindings:

- Pressing <kbd>Enter</kbd> insert a new list item
- Pressing <kbd>Shift+Enter</kbd> split the block in the list item
- Pressing <kbd>Tab</kbd> increase the depth of the item (creates a sub-list)
- Pressing <kbd>Shift+Tab</kbd> decrease the depth of the item
- Pressing <kbd>Delete</kbd> (OSX) or <kbd>Backspace</kbd> at the start, remove the list item (or the list)

Simple validation/normalization (see [assumptions about the schema](#assumption-about-the-schema)):

- Lists can contain only list items, and at least one.
- List items can only be the direct children of a list.
- List items must always contain blocks.

Useful transforms: see [Utilities and Transform](#utilities-and-transform).

### Simple Usage

```js
import EditList from 'slate-edit-list'

const plugins = [
  EditList()
]
```

#### Arguments

This plugin accepts options to redefine the following block types:

- `<String> typeUL="ul_list"` — type for bulleted lists.
- `<String typeOL="ol_list"` — type for numbered lists.
- `<String> typeItem="list_item"` — type for list items.
- `<String> typeDefault="paragraph"` — type for default block in list items.

#### Assumption about the schema

You can use this plugins with custom list block types (using plugin [arguments](#arguments)). But your lists structure should still conform to a few rules. These rules are implemented as schema.

Here is what a minimal list would look like:


```yaml
nodes:
    - kind: block
      type: ul_list # Default type for bulleted lists container
      nodes:
          - kind: block
            type: list_item # List containers can only contain list items
            nodes:
              # List items contain blocks. They cannot be the direct container of text.
              - kind: block
                type: paragraph # Default type of blocks in a list item
                nodes:
                  - kind: text
                    text: Hello World
```

And here is an example of a multi-level list:

```yaml
nodes:
  - kind: block
    type: ol_list
    nodes:
      - kind: block
        type: list_item
        nodes:
          - kind: block
            type: paragraph
            nodes:
              - kind: text
                text: Item 1
          - kind: block
            type: ol_list
            nodes:
              - kind: block
                type: list_item
                nodes:
                  - kind: block
                    type: paragraph
                    nodes:
                      - kind: text
                        text: Item 1.1
              - kind: block
                type: list_item
                nodes:
                  - kind: block
                    type: paragraph
                    nodes:
                      - kind: text
                        text: Item 1.2
```


type Options = {
    containers:    array<string> // All possible types for list containers (default ["unordered-list"])
    item:          string        // Block type for list items (default "list-item")
    defaultBlock:  string        // Block type for default block in list items (default "paragraph")
}

EditList(opts: Options) : Object // Returns an instance of the plugin

plugin.wrapInList(transform: Transform, properties: Object?) : Transform


// The rest stays unchanged


plugin.isSelectionInList(state: State) : Boolean

plugin.isList(node: Node) : Boolean

plugin.getItemDepth(state: State, block: Block?) : Number

plugin.getCurrentItem(state: State, block: Block?) : Block || Void

plugin.getCurrentList(state: State, block: Block?) : Block || Void

plugin.getItemsAtRange(state: State, range: Selection?) : List<Node>

plugin.increaseItemDepth(transform: Transform) : Transform

plugin.decreaseItemDepth(transform: Transform) : Transform

plugin.unwrapList(transform: Transform) : Transform

plugin.splitListItem(transform: Transform) : Transform