From d6d15a2d9bdd1f3fb820246a308d595f6ee10b25 Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Fri, 24 Mar 2017 11:21:52 -0400
Subject: [PATCH 1/7] Add blocks and elements documentation

---
 blocks/README.md  | 166 ++++++++++++++++++++++++++++++++++++++++++++++
 blocks/index.js   |   6 +-
 element/README.md |  65 ++++++++++++++++++
 3 files changed, 235 insertions(+), 2 deletions(-)
 create mode 100644 blocks/README.md
 create mode 100644 element/README.md

diff --git a/blocks/README.md b/blocks/README.md
new file mode 100644
index 0000000000000..1460d1a4c07ec
--- /dev/null
+++ b/blocks/README.md
@@ -0,0 +1,166 @@
+# Blocks
+
+Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.
+
+For more context, refer to [_What Are Little Blocks Made Of?_](https://make.wordpress.org/design/2017/01/25/what-are-little-blocks-made-of/) from the [Make WordPress Design](https://make.wordpress.org/design/) blog.
+
+The following documentation outlines steps you as a developer will need to follow to add your own custom blocks to WordPress's editor interfaces.
+
+## Getting Started
+
+If you're not already accustomed to working with JavaScript in your WordPress plugins, you may first want to reference the guide on [_Including CSS & JavaScript_](https://developer.wordpress.org/themes/basics/including-css-javascript/) in the Theme Handbook.
+
+At a minimum, you will need to enqueue scripts for your block as part of a `block_enqueue_scripts` action callback, with a dependency on the `wp-blocks` script handle:
+
+```php
+<?php
+// plugin.php
+
+function myplugin_block_enqueue_scripts() {
+	wp_enqueue_script( 'myplugin-block', plugins_url( 'block.js', __FILE__ ), array( 'wp-blocks' ) );
+}
+add_action( 'block_enqueue_scripts', 'myplugin_block_enqueue_scripts' );
+```
+
+The following sections will describe what you'll need to include in `block.js` to describe the behavior of your custom block.
+
+## Example
+
+Let's imagine you wanted to define a block to enable you or other users on your site to insert a [Gravatar](http://en.gravatar.com/) image. The URL for a Gravatar image is determined by applying an [md5 hash](https://en.wikipedia.org/wiki/MD5) on an email address and appending it as a path to `gravatar.com/avatar/[hash]`. Of course, it's not a very interesting example if the user can't customize the block, so we'll assume it's a requirement to provide an email address of their choosing.
+
+Take a step back and consider the ideal workflow for adding a Gravatar. After inserting a new "Gravatar" block, as a user I'd expect it to be shown in some empty state, with an option to add an email address in a [text input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). Upon entering an email address, a preview of the image should be shown next to the input. At this point, you might realize that while you'd want some controls to be shown when editing content, the markup included in the published post might not appear the same (your visitors should not see an input field when reading your content). This leads to the first requirement of describing a block: __you will need to provide implementations both for what's to be shown in an editor and what's to be saved with the published content__. You needn't worry about redundant effort here, as concepts of [Elements](../elements/README.md) and componentization provide an avenue for sharing common behaviors.
+
+Now that we've considered user interaction, you should think about the underlying values that determine the markup generated by your block. In our example, the output is affected only when the email address changes. Put another way: __the output of a block is a function of its attributes__. The email address, a simple string, is the only thing we require to be able to generate the image we want to include in the published content. We call these underlying values of a block instance its _attributes_.
+
+With these concepts in mind, let's explore an implementation of our Gravatar block:
+
+```php
+<?php
+// plugin.php
+
+function gravatar_block_enqueue_scripts() {
+	wp_register_script( 'blueimp-md5', 'https://cdnjs.cloudflare.com/ajax/libs/blueimp-md5/2.7.0/js/md5.min.js' );
+	wp_enqueue_script( 'gravatar-block', plugins_url( 'block.js', __FILE__ ), array( 'wp-blocks', 'wp-element', 'blueimp-md5' ) );
+}
+add_action( 'block_enqueue_scripts', 'gravatar_block_enqueue_scripts' );
+```
+
+```js
+// block.js
+
+var el = wp.element.createElement;
+
+function GravatarImage( props ) {
+	var src = 'https://gravatar.com/avatar/' + md5( props.email );
+
+	return el( 'img', { src: props.src } );
+}
+
+wp.blocks.registerBlock( 'myplugin/gravatar', {
+	edit: function( block ) {
+		var email = block.attributes.email,
+			children;
+
+		function onSubmit( event ) {
+			var input = event.target.querySelector( 'input' );
+			block.setAttributes( { email: input.value } );
+			event.preventDefault();
+		}
+
+		function onBlur( event ) {
+			block.setAttributes( { email: event.target.value } );
+		}
+
+		children = el( 'input', { value: email, onBlur: onBlur } );
+		if ( email ) {
+			children.unshift( GravatarImage( { email: email } ) );
+		}
+
+		return el( 'form', { onSubmit: setEmail }, children );
+	},
+	save: function( block ) {
+		return GravatarImage( { email: block.attributes.email } );
+	}
+} );
+```
+
+_[(Example in ES2015+, JSX)](https://gist.github.com/aduth/fb1cc9a2296110a62b96383e4b2e8a7c)_
+
+Let's briefly review a few items you might observe in the implementation:
+
+- There's no built-in JavaScript MD5 hash function, so we pull in [a common implementation](https://github.com/blueimp/JavaScript-MD5).
+- When registering a new block, you must prefix its slug with a namespace for your plugin. This helps prevent conflicts when more than one plugin registers a block with the same slug.
+- You will use `createElement` to describe the structure of your block's markup. See the [Element documentation](../element/README.md) for more information.
+- Extracting `GravatarImage` to a separate function allows us to reuse it in both the editor-specific interface and the published content.
+- The `edit` function should handle any case where an attribute is unset, as in the case of the block being newly inserted, or reset to its original values
+- We only change the attributes of a block by calling the `setAttributes` helper. Never assign a value on the attributes object directly.
+
+There's a few small details that aren't obvious though:
+
+- How are a block's attributes stored when saving a post, so that they're restored next time I edit the same post?
+- Keen to avoid spam, how can I ensure I'm not including the email address in the published content?
+
+The single answer to both of these questions is that the combined state of every block in a post is saved as [post meta](https://codex.wordpress.org/Custom_Fields#Advanced_Techniques_for_Custom_Fields). This ensures that the attributes of a block are preserved and kept separate from the markup between editing sessions. 
+
+## API
+
+### `wp.blocks.registerBlock( slug: string, settings: Object )`
+
+Registers a new block provided a unique slug and an object defining its behavior. Once registered, the block is made available as an option to any editor interface where blocks are implemented.
+
+- `name: string` - A human-readable [localized](https://codex.wordpress.org/I18n_for_WordPress_Developers#Handling_JavaScript_files) label for the block. Shown in the block picker.
+- `edit( { attributes: Object, setAttributes: Function } ): WPElement` - Returns an element describing the markup of a block to be shown in the editor. A block can update its own state in response to events using the `setAttributes` function, passing an object of properties to be applied as a partial update.
+- `save( { attributes: Object } ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
+- `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.
+- `controls: string[]` - Slugs for controls to be made available to block. See also: [`wp.blocks.registerControl`](#wpblocksregistercontrol-slug-string-settings-object-)
+
+### `wp.blocks.registerControl( slug: string, settings: Object )`
+
+Registers a new block-level control. Controls appear in a block's toolbar when it receives focus if it is included in the block's `controls` option.
+
+- `icon: string | WPElement` - Slug of the [Dashicon](https://developer.wordpress.org/resource/dashicons/#awards) to be shown in the control's button, or an element if you choose to render your own SVG.
+- `onClick( { attributes: Object, setAttributes: Function } )` - Click behavior for control. Use this to change or toggle an attribute of the block.
+- `isVisible( { attributes: Object } ): boolean` - Called when a block receives focus or changes. Return `false` to prevent the control's button from being shown. If this option is not defined for a control, the button will always be shown.
+- `isActive( { attributes: Object } ): boolean` - Called when a block receives focus or changes. Return `true` to apply an active effect to the control's button, in the case that the control's behavior is a toggle. 
+
+Inline controls for [`Editable`](#editable) elements are identical for every block and cannot be modified.
+
+### `wp.blocks.getBlockSettings( slug: string )`
+
+Returns settings associated with a registered block.
+
+### `wp.blocks.getControlSettings( slug: string )`
+
+Returns settings associated with a registered control.
+
+## Components
+
+Because many blocks share the same complex behaviors, the following components are made available to simplify implementations of your block's `edit` function.
+
+### `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 similar 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.
+
+The following props are made available:
+
+- `inline: boolean` - If true, only inline elements are allowed to be used in inserted into the text, effectively disabling the behavior of the "Enter" key.
+- `value: string` - Markup value of the editable field. Only valid markup is allowed, as determined by `inline` value and available controls.
+- `onChange: Function` - Callback handler when the value of the field changes, passing the new value as its only argument.
+
+Example:
+
+```js
+var el = wp.element.createElement,
+	Editable = wp.blocks.Editable;
+
+function edit( block ) {
+	function onChange( value ) {
+		block.setAttributes( { text: value } );
+	}
+
+	return el( Editable, {
+		value: block.attributes.text,
+		onChange: onChange
+	} );
+}
+```
diff --git a/blocks/index.js b/blocks/index.js
index 80b987679d540..837a4735e8c4e 100644
--- a/blocks/index.js
+++ b/blocks/index.js
@@ -17,7 +17,9 @@ export { default as parse } from './parser';
 const blocks = {};
 
 /**
- * Registers a block.
+ * Registers a new block provided a unique slug and an object defining its
+ * behavior. Once registered, the block is made available as an option to any
+ * editor interface where blocks are implemented.
  *
  * @param  {string}   slug     Block slug
  * @param  {Object}   settings Block settings
@@ -68,7 +70,7 @@ export function unregisterBlock( slug ) {
 }
 
 /**
- * Returns settings associated with a block.
+ * Returns settings associated with a registered block.
  *
  * @param  {string}  slug Block slug
  * @return {?Object}      Block settings
diff --git a/element/README.md b/element/README.md
new file mode 100644
index 0000000000000..4634d675d0298
--- /dev/null
+++ b/element/README.md
@@ -0,0 +1,65 @@
+Element
+=======
+
+Element is, quite simply, an abstraction layer atop [React](https://facebook.github.io/react/).
+
+You may find yourself asking, "Why an abstraction layer?". For a few reasons:
+
+- In many applications, especially those extended by a rich plugin ecosystem as is the case with WordPress, it's wise to create interfaces to underlying third-party code. The thinking is that if ever a need arises to change or even replace the underlying implementation, it can be done without catestrophic rippling effects to dependent code, so long as the interface stays the same.
+- It provides a mechanism to shield implementers by omitting features with uncertain futures (`createClass`, `PropTypes`).
+- It helps avoid incompatibilities between versions by ensuring that every plugin operates on a single centralized version of the code.
+
+On the `wp.element` global object, you will find the following, ordered roughly be likelihood you'll encounter it in your code:
+
+- [`createElement`](https://facebook.github.io/react/docs/react-api.html#createelement)
+- [`Component`](https://facebook.github.io/react/docs/react-api.html#react.component)
+- [`render`](https://facebook.github.io/react/docs/react-dom.html#render)
+
+## Example
+
+Let's render a customized greeting into an empty element:
+
+```html
+<div id="greeting"></div>
+<script>
+function Greeting( props ) {
+	return wp.element.createElement( 'span', null, 
+		'Hello ' + props.toWhom + '!'
+	);
+}
+
+wp.element.render(
+	wp.element.createElement( Greeting, { toWhom: 'World' } ),
+	document.getElementById( 'app' )
+);
+</script>
+```
+
+Refer to the [official React Quick Start guide](https://facebook.github.io/react/docs/hello-world.html) for a more thorough walkthrough, in most cases substituting `React` and `ReactDOM` with `wp.element` in code examples.
+
+## Why React?
+
+At the risk of igniting debate surrounding any single "best" front-end framework, the choice to use any tool should be motivated specifically to serve the requirements of the system. In modeling the concept of a [block](../blocks/README.md), we observe the following technical requirements:
+
+- An understanding of a block in terms of its underlying values (in the [Gravatar example](../blocks/README.md#example), an email address)
+- A means to describe the UI of a block given these values
+
+At its most basic, React provides a simple input / output mechanism. __Given a set of inputs ("props"), a developer describes the output to be shown on the page.__ This is most elegantly observed in its [function components](https://facebook.github.io/react/docs/components-and-props.html#functional-and-class-components). React serves the role of reconciling the desired output with the current state of the page.
+
+The offerings of any framework necessarily become more complex as these requirements increase; many front-end frameworks prescribe ideas around page routing, retrieving and updating data, and managing layout. React is not immune to this, but the introduced complexity is rarely caused by React itself, but instead managing an arrangement of supporting tools. By moving these concerns out of sight to the internals of the system (WordPress core code), we can minimize the responsibilities of plugin authors to a small, clear set of touch points.
+
+## JSX
+
+While not at all a requirement to use React, [JSX](https://facebook.github.io/react/docs/introducing-jsx.html) is a recommended syntax extension to compose elements more expressively. Through a build process, JSX is converted back to the `createElement` syntax you see earlier in this document.
+
+If you've configured [Babel](http://babeljs.io/) for your project, you can opt in to JSX syntax by specifying the `pragma` option of the [`transform-react-jsx` plugin](https://www.npmjs.com/package/babel-plugin-transform-react-jsx) in your [`.babelrc` configuration](http://babeljs.io/docs/usage/babelrc/).
+
+```json
+{
+	"plugins": [
+		[ "transform-react-jsx", {
+			"pragma": "wp.element.createElement"
+		} ]
+	]
+}
+```

From 3760dc92b1f4c48dde77124e4e09d632a2f06fab Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Fri, 24 Mar 2017 13:07:51 -0400
Subject: [PATCH 2/7] Replace Gravatar example with random image

Demonstrate markup attributes retrieval
---
 blocks/README.md  | 97 ++++++++++++++++++++++++++---------------------
 element/README.md |  3 +-
 2 files changed, 55 insertions(+), 45 deletions(-)

diff --git a/blocks/README.md b/blocks/README.md
index 1460d1a4c07ec..895f3df8371ff 100644
--- a/blocks/README.md
+++ b/blocks/README.md
@@ -26,60 +26,72 @@ The following sections will describe what you'll need to include in `block.js` t
 
 ## Example
 
-Let's imagine you wanted to define a block to enable you or other users on your site to insert a [Gravatar](http://en.gravatar.com/) image. The URL for a Gravatar image is determined by applying an [md5 hash](https://en.wikipedia.org/wiki/MD5) on an email address and appending it as a path to `gravatar.com/avatar/[hash]`. Of course, it's not a very interesting example if the user can't customize the block, so we'll assume it's a requirement to provide an email address of their choosing.
+Let's imagine you wanted to define a block to show a randomly generated image in a post's content using [lorempixel.com](http://lorempixel.com/). The service provides a choice of category and you'd like to offer this as an option when editing the post.
 
-Take a step back and consider the ideal workflow for adding a Gravatar. After inserting a new "Gravatar" block, as a user I'd expect it to be shown in some empty state, with an option to add an email address in a [text input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). Upon entering an email address, a preview of the image should be shown next to the input. At this point, you might realize that while you'd want some controls to be shown when editing content, the markup included in the published post might not appear the same (your visitors should not see an input field when reading your content). This leads to the first requirement of describing a block: __you will need to provide implementations both for what's to be shown in an editor and what's to be saved with the published content__. You needn't worry about redundant effort here, as concepts of [Elements](../elements/README.md) and componentization provide an avenue for sharing common behaviors.
+Take a step back and consider the ideal workflow for adding a new random image. After inserting the block, as a user I'd expect it to be shown in some empty state, with an option to choose a category in a select dropdown. Upon confirming my selection, a preview of the image should be shown next to the dropdown. At this point, you might realize that while you'd want some controls to be shown when editing content, the markup included in the published post might not appear the same (your visitors should not see a dropdown field when reading your content). This leads to the first requirement of describing a block: __you will need to provide implementations both for what's to be shown in an editor and what's to be saved with the published content__. You needn't worry about redundant effort here, as concepts of [Elements](../elements/README.md) and componentization provide an avenue for sharing common behaviors.
 
-Now that we've considered user interaction, you should think about the underlying values that determine the markup generated by your block. In our example, the output is affected only when the email address changes. Put another way: __the output of a block is a function of its attributes__. The email address, a simple string, is the only thing we require to be able to generate the image we want to include in the published content. We call these underlying values of a block instance its _attributes_.
+Now that we've considered user interaction, you should think about the underlying values that determine the markup generated by your block. In our example, the output is affected only when the category changes. Put another way: __the output of a block is a function of its attributes__. The category, a simple string, is the only thing we require to be able to generate the image we want to include in the published content. We call these underlying values of a block instance its _attributes_.
 
-With these concepts in mind, let's explore an implementation of our Gravatar block:
+With these concepts in mind, let's explore an implementation of our random image block:
 
 ```php
 <?php
 // plugin.php
 
-function gravatar_block_enqueue_scripts() {
-	wp_register_script( 'blueimp-md5', 'https://cdnjs.cloudflare.com/ajax/libs/blueimp-md5/2.7.0/js/md5.min.js' );
-	wp_enqueue_script( 'gravatar-block', plugins_url( 'block.js', __FILE__ ), array( 'wp-blocks', 'wp-element', 'blueimp-md5' ) );
+function random_image_block_enqueue_scripts() {
+	wp_enqueue_script( 'random-image-block', plugins_url( 'block.js', __FILE__ ), array( 'wp-blocks', 'wp-element' ) );
 }
-add_action( 'block_enqueue_scripts', 'gravatar_block_enqueue_scripts' );
+add_action( 'block_enqueue_scripts', 'random_image_block_enqueue_scripts' );
 ```
 
 ```js
 // block.js
+var el = wp.element.createElement,
+	query = wp.blocks.query;
 
-var el = wp.element.createElement;
-
-function GravatarImage( props ) {
-	var src = 'https://gravatar.com/avatar/' + md5( props.email );
+function RandomImage( props ) {
+	var src = 'http://lorempixel.com/400/200/' + props.category;
 
-	return el( 'img', { src: props.src } );
+	return el( 'img', {
+		src: src,
+		alt: props.category
+	} );
 }
 
-wp.blocks.registerBlock( 'myplugin/gravatar', {
-	edit: function( block ) {
-		var email = block.attributes.email,
+wp.blocks.registerBlock( 'myplugin/random-image', {
+	attributes: {
+		category: query.attr( 'img', 'alt' )
+	},
+
+	edit: function( attributes, setAttributes ) {
+		var category = attributes.category,
 			children;
 
-		function onSubmit( event ) {
-			var input = event.target.querySelector( 'input' );
-			block.setAttributes( { email: input.value } );
+		function setCategory( event ) {
+			var selected = event.target.querySelector( 'option:checked' );
+			setAttributes( { category: selected.value } );
 			event.preventDefault();
 		}
 
-		function onBlur( event ) {
-			block.setAttributes( { email: event.target.value } );
+		children = [];
+		if ( category ) {
+			children.push( RandomImage( { category: category } ) );
 		}
 
-		children = el( 'input', { value: email, onBlur: onBlur } );
-		if ( email ) {
-			children.unshift( GravatarImage( { email: email } ) );
-		}
+		children.push(
+			el( 'select', { value: category, onChange: setCategory },
+				el( 'option', null, '- Select -' ),
+				el( 'option', { value: 'sports' }, 'Sports' ),
+				el( 'option', { value: 'animals' }, 'Animals' ),
+				el( 'option', { value: 'nature' }, 'Nature' )
+			)
+		);
 
-		return el( 'form', { onSubmit: setEmail }, children );
+		return el( 'form', { onSubmit: setCategory }, children );
 	},
-	save: function( block ) {
-		return GravatarImage( { email: block.attributes.email } );
+
+	save: function( attributes ) {
+		return RandomImage( { category: attributes.category } );
 	}
 } );
 ```
@@ -88,19 +100,18 @@ _[(Example in ES2015+, JSX)](https://gist.github.com/aduth/fb1cc9a2296110a62b963
 
 Let's briefly review a few items you might observe in the implementation:
 
-- There's no built-in JavaScript MD5 hash function, so we pull in [a common implementation](https://github.com/blueimp/JavaScript-MD5).
 - When registering a new block, you must prefix its slug with a namespace for your plugin. This helps prevent conflicts when more than one plugin registers a block with the same slug.
 - You will use `createElement` to describe the structure of your block's markup. See the [Element documentation](../element/README.md) for more information.
-- Extracting `GravatarImage` to a separate function allows us to reuse it in both the editor-specific interface and the published content.
-- The `edit` function should handle any case where an attribute is unset, as in the case of the block being newly inserted, or reset to its original values
+- Extracting `RandomImage` to a separate function allows us to reuse it in both the editor-specific interface and the published content.
+- The `edit` function should handle any case where an attribute is unset, as in the case of the block being newly inserted.
 - We only change the attributes of a block by calling the `setAttributes` helper. Never assign a value on the attributes object directly.
+- React provides conveniences for working with `select` element with [`value` and `onChange` props](https://facebook.github.io/react/docs/forms.html#the-select-tag).
 
-There's a few small details that aren't obvious though:
+By concerning yourself only with describing the markup of a block given its attributes, you need not worry about maintaining the state of the page, or how your block interacts in the context of the surrounding editor. 
 
-- How are a block's attributes stored when saving a post, so that they're restored next time I edit the same post?
-- Keen to avoid spam, how can I ensure I'm not including the email address in the published content?
+But how does the markup become an object of attributes? We need a pattern for encoding the values into the published post's markup, and then retrieving them the next time the post is edited. This is the motivation for the block's `attributes` property. The shape of this object matches that of the attributes object we'd like to receive, where each value is a [__matcher__](http://github.com/aduth/hpq) which tries to find the desired value from the markup of the block.
 
-The single answer to both of these questions is that the combined state of every block in a post is saved as [post meta](https://codex.wordpress.org/Custom_Fields#Advanced_Techniques_for_Custom_Fields). This ensures that the attributes of a block are preserved and kept separate from the markup between editing sessions. 
+In the random image block above, we've given the `alt` attribute of the image a secondary responsibility of tracking the selected category. There are a few other ways we could have achieved this, but the category value happens to work well as an `alt` descriptor. In the `attributes` property, we define an object with a key of `category` whose value tries to find this `alt` attribute of the markup. If it's successful, the category's value in our `edit` and `save` functions will be assigned. In the case of a new block or invalid markup, this value would be `undefined`, so we adjust our return value accordingly.
 
 ## API
 
@@ -109,8 +120,8 @@ The single answer to both of these questions is that the combined state of every
 Registers a new block provided a unique slug and an object defining its behavior. Once registered, the block is made available as an option to any editor interface where blocks are implemented.
 
 - `name: string` - A human-readable [localized](https://codex.wordpress.org/I18n_for_WordPress_Developers#Handling_JavaScript_files) label for the block. Shown in the block picker.
-- `edit( { attributes: Object, setAttributes: Function } ): WPElement` - Returns an element describing the markup of a block to be shown in the editor. A block can update its own state in response to events using the `setAttributes` function, passing an object of properties to be applied as a partial update.
-- `save( { attributes: Object } ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
+- `edit( attributes: Object, setAttributes: Function ): WPElement` - Returns an element describing the markup of a block to be shown in the editor. A block can update its own state in response to events using the `setAttributes` function, passing an object of properties to be applied as a partial update.
+- `save( attributes: Object ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
 - `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.
 - `controls: string[]` - Slugs for controls to be made available to block. See also: [`wp.blocks.registerControl`](#wpblocksregistercontrol-slug-string-settings-object-)
 
@@ -119,9 +130,9 @@ Registers a new block provided a unique slug and an object defining its behavior
 Registers a new block-level control. Controls appear in a block's toolbar when it receives focus if it is included in the block's `controls` option.
 
 - `icon: string | WPElement` - Slug of the [Dashicon](https://developer.wordpress.org/resource/dashicons/#awards) to be shown in the control's button, or an element if you choose to render your own SVG.
-- `onClick( { attributes: Object, setAttributes: Function } )` - Click behavior for control. Use this to change or toggle an attribute of the block.
-- `isVisible( { attributes: Object } ): boolean` - Called when a block receives focus or changes. Return `false` to prevent the control's button from being shown. If this option is not defined for a control, the button will always be shown.
-- `isActive( { attributes: Object } ): boolean` - Called when a block receives focus or changes. Return `true` to apply an active effect to the control's button, in the case that the control's behavior is a toggle. 
+- `onClick( attributes: Object, setAttributes: Function )` - Click behavior for control. Use this to change or toggle an attribute of the block.
+- `isVisible( attributes: Object ): boolean` - Called when a block receives focus or changes. Return `false` to prevent the control's button from being shown. If this option is not defined for a control, the button will always be shown.
+- `isActive( attributes: Object ): boolean` - Called when a block receives focus or changes. Return `true` to apply an active effect to the control's button, in the case that the control's behavior is a toggle. 
 
 Inline controls for [`Editable`](#editable) elements are identical for every block and cannot be modified.
 
@@ -153,13 +164,13 @@ Example:
 var el = wp.element.createElement,
 	Editable = wp.blocks.Editable;
 
-function edit( block ) {
+function edit( attributes, setAttributes ) {
 	function onChange( value ) {
-		block.setAttributes( { text: value } );
+		setAttributes( { text: value } );
 	}
 
 	return el( Editable, {
-		value: block.attributes.text,
+		value: attributes.text,
 		onChange: onChange
 	} );
 }
diff --git a/element/README.md b/element/README.md
index 4634d675d0298..de69ef720523a 100644
--- a/element/README.md
+++ b/element/README.md
@@ -12,7 +12,6 @@ You may find yourself asking, "Why an abstraction layer?". For a few reasons:
 On the `wp.element` global object, you will find the following, ordered roughly be likelihood you'll encounter it in your code:
 
 - [`createElement`](https://facebook.github.io/react/docs/react-api.html#createelement)
-- [`Component`](https://facebook.github.io/react/docs/react-api.html#react.component)
 - [`render`](https://facebook.github.io/react/docs/react-dom.html#render)
 
 ## Example
@@ -41,7 +40,7 @@ Refer to the [official React Quick Start guide](https://facebook.github.io/react
 
 At the risk of igniting debate surrounding any single "best" front-end framework, the choice to use any tool should be motivated specifically to serve the requirements of the system. In modeling the concept of a [block](../blocks/README.md), we observe the following technical requirements:
 
-- An understanding of a block in terms of its underlying values (in the [Gravatar example](../blocks/README.md#example), an email address)
+- An understanding of a block in terms of its underlying values (in the [random image example](../blocks/README.md#example), a category)
 - A means to describe the UI of a block given these values
 
 At its most basic, React provides a simple input / output mechanism. __Given a set of inputs ("props"), a developer describes the output to be shown on the page.__ This is most elegantly observed in its [function components](https://facebook.github.io/react/docs/components-and-props.html#functional-and-class-components). React serves the role of reconciling the desired output with the current state of the page.

From 6700d02c2acc6920dec74cf0de0d221f176e2acd Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Fri, 24 Mar 2017 13:10:37 -0400
Subject: [PATCH 3/7] Prescribe comment metadata attribute behavior

---
 blocks/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/blocks/README.md b/blocks/README.md
index 895f3df8371ff..b5e1f1500be8f 100644
--- a/blocks/README.md
+++ b/blocks/README.md
@@ -124,6 +124,7 @@ Registers a new block provided a unique slug and an object defining its behavior
 - `save( attributes: Object ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
 - `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.
 - `controls: string[]` - Slugs for controls to be made available to block. See also: [`wp.blocks.registerControl`](#wpblocksregistercontrol-slug-string-settings-object-)
+- `encodeAttributes( attributes: Object ): Object` - Called before save, this function allows you to control which attributes are to be saved in the block comment metadata. By default, all attribute values not defined in the block's `attributes` property are serialized to the comment metadata.
 
 ### `wp.blocks.registerControl( slug: string, settings: Object )`
 

From 46689f49d55ffffaed29d2e1e6e3915a23753b0f Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Fri, 24 Mar 2017 13:16:18 -0400
Subject: [PATCH 4/7] Rename "name" as "title", use consistently

---
 blocks/README.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/blocks/README.md b/blocks/README.md
index b5e1f1500be8f..16fe7757c59de 100644
--- a/blocks/README.md
+++ b/blocks/README.md
@@ -59,6 +59,8 @@ function RandomImage( props ) {
 }
 
 wp.blocks.registerBlock( 'myplugin/random-image', {
+	title: 'Random Image',
+
 	attributes: {
 		category: query.attr( 'img', 'alt' )
 	},
@@ -119,7 +121,7 @@ In the random image block above, we've given the `alt` attribute of the image a
 
 Registers a new block provided a unique slug and an object defining its behavior. Once registered, the block is made available as an option to any editor interface where blocks are implemented.
 
-- `name: string` - A human-readable [localized](https://codex.wordpress.org/I18n_for_WordPress_Developers#Handling_JavaScript_files) label for the block. Shown in the block picker.
+- `title: string` - A human-readable [localized](https://codex.wordpress.org/I18n_for_WordPress_Developers#Handling_JavaScript_files) label for the block. Shown in the block picker.
 - `edit( attributes: Object, setAttributes: Function ): WPElement` - Returns an element describing the markup of a block to be shown in the editor. A block can update its own state in response to events using the `setAttributes` function, passing an object of properties to be applied as a partial update.
 - `save( attributes: Object ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
 - `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.
@@ -130,6 +132,7 @@ Registers a new block provided a unique slug and an object defining its behavior
 
 Registers a new block-level control. Controls appear in a block's toolbar when it receives focus if it is included in the block's `controls` option.
 
+- `title: string` - A human-readable [localized](https://codex.wordpress.org/I18n_for_WordPress_Developers#Handling_JavaScript_files) label for the control. Shown in help tooltips.
 - `icon: string | WPElement` - Slug of the [Dashicon](https://developer.wordpress.org/resource/dashicons/#awards) to be shown in the control's button, or an element if you choose to render your own SVG.
 - `onClick( attributes: Object, setAttributes: Function )` - Click behavior for control. Use this to change or toggle an attribute of the block.
 - `isVisible( attributes: Object ): boolean` - Called when a block receives focus or changes. Return `false` to prevent the control's button from being shown. If this option is not defined for a control, the button will always be shown.

From 18c427ac86b6d7b9d2491f5a5cb2c11add51dcd1 Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Fri, 24 Mar 2017 13:16:29 -0400
Subject: [PATCH 5/7] Document icon usage for blocks

---
 blocks/README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/blocks/README.md b/blocks/README.md
index 16fe7757c59de..42364b5ff4d27 100644
--- a/blocks/README.md
+++ b/blocks/README.md
@@ -61,6 +61,8 @@ function RandomImage( props ) {
 wp.blocks.registerBlock( 'myplugin/random-image', {
 	title: 'Random Image',
 
+	icon: 'format-image',
+
 	attributes: {
 		category: query.attr( 'img', 'alt' )
 	},
@@ -122,6 +124,7 @@ In the random image block above, we've given the `alt` attribute of the image a
 Registers a new block provided a unique slug and an object defining its behavior. Once registered, the block is made available as an option to any editor interface where blocks are implemented.
 
 - `title: string` - A human-readable [localized](https://codex.wordpress.org/I18n_for_WordPress_Developers#Handling_JavaScript_files) label for the block. Shown in the block picker.
+- `icon: string | WPElement` - Slug of the [Dashicon](https://developer.wordpress.org/resource/dashicons/#awards) to be shown in the control's button, or an element if you choose to render your own SVG.
 - `edit( attributes: Object, setAttributes: Function ): WPElement` - Returns an element describing the markup of a block to be shown in the editor. A block can update its own state in response to events using the `setAttributes` function, passing an object of properties to be applied as a partial update.
 - `save( attributes: Object ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
 - `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.

From 4dde9a9a4ff27dce8f929c7f26d547dbefafc6d8 Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Fri, 24 Mar 2017 13:22:27 -0400
Subject: [PATCH 6/7] Clarify expected encodeAttributes behavior

---
 blocks/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/blocks/README.md b/blocks/README.md
index 42364b5ff4d27..6d0973c4062e7 100644
--- a/blocks/README.md
+++ b/blocks/README.md
@@ -129,7 +129,7 @@ Registers a new block provided a unique slug and an object defining its behavior
 - `save( attributes: Object ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
 - `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.
 - `controls: string[]` - Slugs for controls to be made available to block. See also: [`wp.blocks.registerControl`](#wpblocksregistercontrol-slug-string-settings-object-)
-- `encodeAttributes( attributes: Object ): Object` - Called before save, this function allows you to control which attributes are to be saved in the block comment metadata. By default, all attribute values not defined in the block's `attributes` property are serialized to the comment metadata.
+- `encodeAttributes( attributes: Object ): Object` - Called when save markup is generated, this function allows you to control which attributes are to be encoded in the block comment metadata. By default, all attribute values not defined in the block's `attributes` property are serialized to the comment metadata. If defined, this function should return the subset of attributes to encode, or `null` to bypass default behavior.
 
 ### `wp.blocks.registerControl( slug: string, settings: Object )`
 

From 1058509dd36d573300e5ca9fb3247b6d8f0d61f1 Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Fri, 24 Mar 2017 13:24:18 -0400
Subject: [PATCH 7/7] Remove tagName from supported block properties
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Needed primarily as solution to excess meta storage. Could still be
useful as convenience for core block types, but let’s revisit it when
deemed necessary.
---
 blocks/README.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/blocks/README.md b/blocks/README.md
index 6d0973c4062e7..f7d740219955b 100644
--- a/blocks/README.md
+++ b/blocks/README.md
@@ -127,7 +127,6 @@ Registers a new block provided a unique slug and an object defining its behavior
 - `icon: string | WPElement` - Slug of the [Dashicon](https://developer.wordpress.org/resource/dashicons/#awards) to be shown in the control's button, or an element if you choose to render your own SVG.
 - `edit( attributes: Object, setAttributes: Function ): WPElement` - Returns an element describing the markup of a block to be shown in the editor. A block can update its own state in response to events using the `setAttributes` function, passing an object of properties to be applied as a partial update.
 - `save( attributes: Object ): WPElement` - Returns an element describing the markup of a block to be saved in the published content. This function is called before save and when switching to an editor's HTML view.
-- `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.
 - `controls: string[]` - Slugs for controls to be made available to block. See also: [`wp.blocks.registerControl`](#wpblocksregistercontrol-slug-string-settings-object-)
 - `encodeAttributes( attributes: Object ): Object` - Called when save markup is generated, this function allows you to control which attributes are to be encoded in the block comment metadata. By default, all attribute values not defined in the block's `attributes` property are serialized to the comment metadata. If defined, this function should return the subset of attributes to encode, or `null` to bypass default behavior.