From c59ba95053cd7b37b3db87ee270022870b5a9f41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ella=20Van=C2=A0Dorpe?= <iseulde@automattic.com>
Date: Wed, 31 Jan 2018 13:11:07 +0100
Subject: [PATCH] Add Editable readme (#1832)

* WIP: Add Editable readme

* typo fixes

* Add onSplit, onReplace, onMerge, onRemove to docs

* Add formattingControls and keepPlaceholderOnFocus to docs

* Add Editable API docs to Block API docs

* Add ESNext
---
 blocks/editable/readme.md | 125 ++++++++++++++++++++++++++++++++++++++
 docs/manifest.json        |   6 ++
 2 files changed, 131 insertions(+)
 create mode 100644 blocks/editable/readme.md

diff --git a/blocks/editable/readme.md b/blocks/editable/readme.md
new file mode 100644
index 00000000000000..ebe63df9f28f6d
--- /dev/null
+++ b/blocks/editable/readme.md
@@ -0,0 +1,125 @@
+# `Editable`
+
+Render a rich
+[`contenteditable` input](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content),
+providing users the option to add emphasis to content or links to content. It
+behaves similarly to a
+[controlled component](https://facebook.github.io/react/docs/forms.html#controlled-components),
+except that `onChange` is triggered less frequently than would be expected from
+a traditional `input` field, usually when the user exits the field.
+
+## Properties
+
+### `value: Array`
+
+*Required.* Array of React DOM to make editable. The rendered HTML should be valid, and valid with respect to the `tagName` and `inline` property.
+
+### `onChange( value: Array ): Function`
+
+*Required.* Called when the value changes.
+
+### `tagName: String`
+
+*Default: `div`.* The [tag name](https://www.w3.org/TR/html51/syntax.html#tag-name) of the editable element.
+
+### `placeholder: String`
+
+*Optional.* Placeholder text to show when the field is empty, similar to the
+  [`input` and `textarea` attribute of the same name](https://developer.mozilla.org/en-US/docs/Learn/HTML/Forms/HTML5_updates#The_placeholder_attribute).
+
+### `focus: { offset: Number }`
+
+*Optional.* Whether to focus the editable or not. We currently support an offset of -1 to move the focus to the end of the editable.
+
+### `onFocus( focus: Object ): Function`
+
+*Optional.* Called when the editable receives focus.
+
+### `multiline: String`
+
+*Optional.* By default, a line break will be inserted on <kbd>Enter</kbd>. If the editable field can contain multiple paragraphs, this property can be set to `p` to create new paragraphs on <kbd>Enter</kbd>.
+
+### `onSplit( before: Array, after: Array, ...blocks: Object ): Function`
+
+*Optional.* Called when the content can be split with `before` and `after`. There might be blocks present, which should be inserted in between.
+
+### `onReplace( blocks: Array ): Function`
+
+*Optional.* Called when the `Editable` instance is empty and it can be replaced with the given blocks.
+
+### `onMerge( forward: Boolean ): Function`
+
+*Optional.* Called when blocks can be merged. `forward` is true when merging with the next block, false when merging with the previous block.
+
+### `onRemove( forward: Boolean ): Function`
+
+*Optional.* Called when the block can be removed. `forward` is true when the selection is expected to move to the next block, false to the previous block.
+
+### `formattingControls: Array`
+
+*Optional.* By default, all formatting controls are present. This setting can be used to fine-tune formatting controls. Possible items: `[ 'bold', 'italic', 'strikethrough', 'link' ]`.
+
+### `keepPlaceholderOnFocus: Boolean`
+
+*Optional.* By default, the placeholder will hide as soon as the editable field receives focus. With this setting it can be be kept while the field is focussed and empty.
+
+## Example
+
+{% codetabs %}
+{% ES5 %}
+```js
+wp.blocks.registerBlockType( /* ... */, {
+	// ...
+
+	attributes: {
+		content: {
+			type: 'array',
+			source: 'children',
+			selector: 'h2',
+		},
+	},
+
+	edit: function( props ) {
+		return wp.element.createElement( wp.blocks.Editable, {
+			tagName: 'h2',
+			className: props.className,
+			value: props.attributes.content,
+			onChange: function( content ) {
+				props.setAttributes( { content: content } );
+			},
+			focus: props.focus,
+			onFocus: props.setFocus,
+		} );
+	},
+} );
+```
+{% ESNext %}
+```js
+const { registerBlockType, Editable } = wp.blocks;
+
+registerBlockType( /* ... */, {
+	// ...
+
+	attributes: {
+		content: {
+			type: 'array',
+			source: 'children',
+			selector: 'h2',
+		},
+	},
+
+	edit( { className, attributes, setAttributes, focus, setFocus } ) {
+		return (
+			<Editable
+				tagName="h2"
+				className={ className }
+				value={ attributes.content }
+				onChange={ ( content ) => setAttributes( { content } ) }
+				focus={ focus }
+				setFocus={ setFocus }
+			/>
+		);
+	},
+} );
+```
+{% end %}
diff --git a/docs/manifest.json b/docs/manifest.json
index 554cae7459d71a..e3b609024d27de 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -29,6 +29,12 @@
 		"markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/block-edit-save.md",
 		"parent": "block-api"
 	},
+	{
+		"title": "Editable API",
+		"slug": "editable-api",
+		"markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/blocks\/editable\/readme.md",
+		"parent": "block-api"
+	},
 	{
 		"title": "Deprecated Blocks",
 		"slug": "deprecated-blocks",