Documentation: Update the attributes' documentation to match the late…

…st API changes

blocks/README.md

@@ -138,7 +138,9 @@ add_action( 'enqueue_block_editor_assets', 'random_image_enqueue_block_editor_as
 		attributes: {
 			category: {
 				type: 'string',
-				source: source.attr( 'img', 'alt' )
+				source: 'attribute',
+				attribute: 'alt',
+				selector: 'img',
 			}
 		},
 
@@ -238,8 +240,8 @@ editor interface where blocks are implemented.
   keys of the object define the shape of attributes, and each value an object
   schema describing the `type`, `default` (optional), and
   [`source`](http://gutenberg-devdoc.surge.sh/reference/attributes/)
-  (optional) of the attribute. If `source` is omitted, the attribute is 
-  serialized into the block's comment delimiters. Alternatively, define 
+  (optional) of the attribute. If `source` is omitted, the attribute is
+  serialized into the block's comment delimiters. Alternatively, define
   `attributes` as a function which returns the attributes object.
 - `category: string` - Slug of the block's category. The category is used to
   organize the blocks in the block inserter.

docs/attributes.md

@@ -8,21 +8,85 @@ Each source accepts an optional selector as the first argument. If a selector is
 
 Under the hood, attribute sources are a superset of functionality provided by [hpq](https://github.com/aduth/hpq), a small library used to parse and query HTML markup into an object shape. In an object of attributes sources, you can name the keys as you see fit. The resulting object will assign as a value to each key the result of its attribute source.
 
-### `attr`
+### `attribute`
 
-Use `attr` to extract the value of an attribute from markup.
+Use `attribute` to extract the value of an attribute from markup.
 
 _Example_: Extract the `src` attribute from an image found in the block's markup.
 
 ```js
 {
 	url: {
-		source: attr( 'img', 'src' )
+		source: 'attribute',
+		selector: 'img',
+		attribute: 'src',
 	}
 }
 // { "url": "https://lorempixel.com/1200/800/" }
 ```
 
+### `attribute`
+
+Use `attribute` to extract the value of an attribute from markup.
+
+_Example_: Extract the `src` attribute from an image found in the block's markup.
+
+```js
+{
+	url: {
+		source: 'attribute',
+		selector: 'img',
+		attribute: 'src',
+	}
+}
+// { "url": "https://lorempixel.com/1200/800/" }
+```
+
+### `property`
+
+Use `property` to extract the value of a property of a DOM Node from markup.
+
+_Example_: Extract the `nodeName` property from a heading's node.
+
+```js
+{
+	tagName: {
+		source: 'property',
+		selector: 'h1,h2,h3,h4,h5,h6',
+		property: 'nodeName',
+	}
+}
+// { "tagName": "h2" }
+```
+
+### `text`
+
+Use `text` to extract the inner text from markup.
+
+```js
+{
+	content: {
+		source: 'text',
+		selector: 'figcaption',
+	}
+}
+// { "content": "The inner text of the figcaption element" }
+```
+
+### `html`
+
+Use `html` to extract the inner HTML from markup.
+
+```js
+{
+	content: {
+		source: 'html',
+		selector: 'figcaption',
+	}
+}
+// { "content": "The inner text of the <strong>figcaption</strong> element" }
+```
+
 ### `children`
 
 Use `children` to extract child nodes of the matched element, returned as an array of virtual elements. This is most commonly used in combination with the `Editable` component.
@@ -32,13 +96,14 @@ _Example_: Extract child nodes from a paragraph of rich text.
 ```js
 {
 	content: {
-		source: children( 'p' )
+		source: 'children',
+		selector: 'p'
 	}
 }
 // {
 //   "content": [
 //     "Vestibulum eu ",
-//     { "type": "strong", "children": "tortor" }, 
+//     { "type": "strong", "children": "tortor" },
 //     " vel urna."
 //   ]
 // }
@@ -53,14 +118,19 @@ _Example_: Extract `src` and `alt` from each image element in the block's markup
 ```js
 {
 	images: {
-		source: query( 'img', {
-			url: attr( 'src' )
-			alt: attr( 'alt' )
-		} )
+		source: 'query'
+		selector: 'img',
+		query: {
+			source: 'object',
+			object: {
+				url: { source: 'attribute', attribute: 'src' },
+				alt: { source: 'attribute', attribute: 'alt' },
+			},
+		}
 	}
 }
 // {
-//   "images": [ 
+//   "images": [
 //     { "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
 //     { "url": "https://lorempixel.com/50/50/", "alt": "small image" }
 //   ]
@@ -75,6 +145,7 @@ Attributes may be obtained from a post's meta rather than from the block's repre
 attributes: {
 	author: {
 		type: 'string',
+		source: 'meta',
 		meta: 'author'
 	},
 },

docs/block-api.md

@@ -76,11 +76,14 @@ Attributes provide the structured data needs of a block. They can exist in diffe
 attributes: {
 	cover: {
 		type: 'string',
-		source: attr( 'img', 'src' ),
+		source: 'attribute',
+		selector: 'img',
+		attribute: 'src',
 	},
 	author: {
 		type: 'string',
-		source: children( '.book-author' ),
+		source: 'children',
+		selector: '.book-author',
 	},
 	pages: {
 		type: 'number',

docs/blocks-controls.md

@@ -17,8 +17,7 @@ var el = wp.element.createElement,
 	registerBlockType = wp.blocks.registerBlockType,
 	Editable = wp.blocks.Editable,
 	BlockControls = wp.blocks.BlockControls,
-	AlignmentToolbar = wp.blocks.AlignmentToolbar,
-	children = wp.blocks.source.children;
+	AlignmentToolbar = wp.blocks.AlignmentToolbar;
 
 registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-04', {
 	title: 'Hello World (Step 4)',
@@ -30,7 +29,8 @@ registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-04', {
 	attributes: {
 		content: {
 			type: 'array',
-			source: children( 'p' )
+			source: 'children',
+			selector: 'p',
 		}
 	},
 
@@ -91,7 +91,6 @@ const {
 	AlignmentToolbar,
 	source
 } = wp.blocks;
-const { children } = source;
 
 registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-04', {
 	title: 'Hello World (Step 4)',
@@ -103,7 +102,8 @@ registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-04', {
 	attributes: {
 		content: {
 			type: 'array',
-			source: children( 'p' ),
+			source: 'children',
+			selector: 'p',
 		},
 	},
 

docs/blocks-editable.md

@@ -13,8 +13,7 @@ One challenge of maintaining the representation of a block as a JavaScript objec
 ```js
 var el = wp.element.createElement,
 	registerBlockType = wp.blocks.registerBlockType,
-	Editable = wp.blocks.Editable,
-	children = wp.blocks.source.children;
+	Editable = wp.blocks.Editable;
 
 registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', {
 	title: 'Hello World (Step 3)',
@@ -26,7 +25,8 @@ registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', {
 	attributes: {
 		content: {
 			type: 'array',
-			source: children( 'p' )
+			source: 'children',
+			selector: 'p',
 		}
 	},
 
@@ -61,7 +61,6 @@ registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', {
 {% ESNext %}
 ```js
 const { registerBlockType, Editable, source } = wp.blocks;
-const { children } = source;
 
 registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-03', {
 	title: 'Hello World (Step 3)',
@@ -73,7 +72,8 @@ registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-03', {
 	attributes: {
 		content: {
 			type: 'array',
-			source: children( 'p' ),
+			source: 'children',
+			selector: 'p',
 		},
 	},