Merge pull request #1902 from WordPress/update/query-to-matchers

Rename blocks.query as blocks.source

blocks/README.md

@@ -117,7 +117,7 @@ add_action( 'enqueue_block_editor_assets', 'random_image_enqueue_block_editor_as
 // block.js
 ( function( blocks, element ) {
 	var el = element.createElement,
-		query = blocks.query;
+		source = blocks.source;
 
 	function RandomImage( props ) {
 		var src = 'http://lorempixel.com/400/200/' + props.category;
@@ -138,7 +138,7 @@ add_action( 'enqueue_block_editor_assets', 'random_image_enqueue_block_editor_as
 		attributes: {
 			category: {
 				type: 'string',
-				source: query.attr( 'img', 'alt' )
+				source: source.attr( 'img', 'alt' )
 			}
 		},
 
@@ -207,7 +207,7 @@ 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)
+[__source__](http://github.com/aduth/hpq)
 which tries to find the desired value from the markup of the block.
 
 In the random image block above, we've given the `alt` attribute of the image a
@@ -237,7 +237,7 @@ editor interface where blocks are implemented.
 - `attributes: Object | Function` - An object of attribute schemas, where the
   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/attribute-matchers/)
+  [`source`](http://gutenberg-devdoc.surge.sh/reference/attribute-sources/)
   (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.

blocks/api/index.js

@@ -1,9 +1,9 @@
 /**
  * External dependencies
  */
-import * as query from './query';
+import * as source from './source';
 
-export { query };
+export { source };
 export { createBlock, switchToBlockType } from './factory';
 export { default as parse } from './parser';
 export { default as pasteHandler } from './paste';

blocks/api/parser.js

@@ -31,7 +31,7 @@ import { isValidBlock } from './validation';
  * @return {Boolean}         Whether function is an attribute source
  */
 export function isValidSource( source ) {
-	return !! source && '_wpBlocksKnownMatcher' in source;
+	return !! source && '_wpBlocksKnownSource' in source;
 }
 
 /**

blocks/api/paste.js

@@ -90,7 +90,7 @@ export default function( nodes ) {
 			const transformsFrom = get( blockType, 'transforms.from', [] );
 			const transform = find( transformsFrom, ( { type } ) => type === 'raw' );
 
-			if ( ! transform || ! transform.matcher( node ) ) {
+			if ( ! transform || ! transform.source( node ) ) {
 				return acc;
 			}
 

blocks/api/source.js

@@ -0,0 +1,63 @@
+/**
+ * WordPress dependencies
+ */
+import { createElement } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import { nodeListToReact, nodeToReact } from 'dom-react';
+import { flow } from 'lodash';
+import {
+	attr as originalAttr,
+	prop as originalProp,
+	html as originalHtml,
+	text as originalText,
+	query as originalQuery,
+} from 'hpq';
+
+/**
+ * Given a source function creator, returns a new function which applies an
+ * internal flag to the created source.
+ *
+ * @param  {Function} fn Original source function creator
+ * @return {Function}    Modified source function creator
+ */
+function withKnownSourceFlag( fn ) {
+	return flow( fn, ( source ) => {
+		source._wpBlocksKnownSource = true;
+		return source;
+	} );
+}
+
+export const attr = withKnownSourceFlag( originalAttr );
+export const prop = withKnownSourceFlag( originalProp );
+export const html = withKnownSourceFlag( originalHtml );
+export const text = withKnownSourceFlag( originalText );
+export const query = withKnownSourceFlag( originalQuery );
+export const children = withKnownSourceFlag( ( selector ) => {
+	return ( domNode ) => {
+		let match = domNode;
+
+		if ( selector ) {
+			match = domNode.querySelector( selector );
+		}
+
+		if ( match ) {
+			return nodeListToReact( match.childNodes || [], createElement );
+		}
+
+		return [];
+	};
+} );
+export const node = withKnownSourceFlag( ( selector ) => {
+	return ( domNode ) => {
+		let match = domNode;
+
+		if ( selector ) {
+			match = domNode.querySelector( selector );
+		}
+
+		return nodeToReact( match, createElement );
+	};
+} );

blocks/api/test/parser.js

@@ -6,7 +6,7 @@ import { noop } from 'lodash';
 /**
  * Internal dependencies
  */
-import { text, attr, html } from '../query';
+import { text, attr, html } from '../source';
 import {
 	isValidSource,
 	getBlockAttributes,

blocks/api/test/serializer.js

@@ -6,7 +6,7 @@ import { createElement, Component } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { text } from '../query';
+import { text } from '../source';
 import serialize, {
 	getCommentAttributes,
 	getBeautifulContent,

blocks/api/test/query.js → blocks/api/test/source.js

@@ -11,44 +11,44 @@ import { renderToString } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import * as query from '../query';
+import * as sources from '../source';
 
-describe( 'query', () => {
-	it( 'should generate matchers which apply internal flag', () => {
-		for ( const matcherFn in query ) {
-			expect( query[ matcherFn ]()._wpBlocksKnownMatcher ).toBe( true );
+describe( 'sources', () => {
+	it( 'should generate sources which apply internal flag', () => {
+		for ( const sourceFn in sources ) {
+			expect( sources[ sourceFn ]()._wpBlocksKnownSource ).toBe( true );
 		}
 	} );
 
 	describe( 'children()', () => {
-		it( 'should return a matcher function', () => {
-			const matcher = query.children();
+		it( 'should return a source function', () => {
+			const source = sources.children();
 
-			expect( typeof matcher ).toBe( 'function' );
+			expect( typeof source ).toBe( 'function' );
 		} );
 
 		it( 'should return HTML equivalent WPElement of matched element', () => {
 			// Assumption here is that we can cleanly convert back and forth
 			// between a string and WPElement representation
 			const html = '<blockquote><p>A delicious sundae dessert</p></blockquote>';
-			const match = parse( html, query.children() );
+			const match = parse( html, sources.children() );
 
 			expect( renderToString( match ) ).toBe( html );
 		} );
 	} );
 
 	describe( 'node()', () => {
-		it( 'should return a matcher function', () => {
-			const matcher = query.node();
+		it( 'should return a source function', () => {
+			const source = sources.node();
 
-			expect( typeof matcher ).toBe( 'function' );
+			expect( typeof source ).toBe( 'function' );
 		} );
 
 		it( 'should return HTML equivalent WPElement of matched element', () => {
 			// Assumption here is that we can cleanly convert back and forth
 			// between a string and WPElement representation
 			const html = '<blockquote><p>A delicious sundae dessert</p></blockquote>';
-			const match = parse( html, query.node() );
+			const match = parse( html, sources.node() );
 
 			expect( renderToString( match ) ).toBe( `<body>${ html }</body>` );
 		} );

blocks/library/button/index.js

@@ -9,15 +9,15 @@ import { IconButton } from '@wordpress/components';
  */
 import './style.scss';
 import './block.scss';
-import { registerBlockType, query } from '../../api';
+import { registerBlockType, source } from '../../api';
 import Editable from '../../editable';
 import UrlInput from '../../url-input';
 import BlockControls from '../../block-controls';
 import BlockAlignmentToolbar from '../../block-alignment-toolbar';
 import ColorPalette from '../../color-palette';
 import InspectorControls from '../../inspector-controls';
 
-const { attr, children } = query;
+const { attr, children } = source;
 
 registerBlockType( 'core/button', {
 	title: __( 'Button' ),

blocks/library/code/index.js

@@ -12,9 +12,9 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlockType, query, createBlock } from '../../api';
+import { registerBlockType, source, createBlock } from '../../api';
 
-const { prop } = query;
+const { prop } = source;
 
 registerBlockType( 'core/code', {
 	title: __( 'Code' ),

blocks/library/cover-image/index.js

@@ -10,7 +10,7 @@ import classnames from 'classnames';
  */
 import './style.scss';
 import './block.scss';
-import { registerBlockType, query } from '../../api';
+import { registerBlockType, source } from '../../api';
 import Editable from '../../editable';
 import MediaUploadButton from '../../media-upload-button';
 import BlockControls from '../../block-controls';
@@ -19,7 +19,7 @@ import InspectorControls from '../../inspector-controls';
 import ToggleControl from '../../inspector-controls/toggle-control';
 import BlockDescription from '../../block-description';
 
-const { text } = query;
+const { text } = source;
 
 const validAlignments = [ 'left', 'center', 'right', 'wide', 'full' ];
 

blocks/library/cover-text/index.js

@@ -8,7 +8,7 @@ import { concatChildren } from '@wordpress/element';
  * Internal dependencies
  */
 import './block.scss';
-import { registerBlockType, query as hpq } from '../../api';
+import { registerBlockType, source } from '../../api';
 import AlignmentToolbar from '../../alignment-toolbar';
 import BlockControls from '../../block-controls';
 import BlockAlignmentToolbar from '../../block-alignment-toolbar';
@@ -18,7 +18,7 @@ import InspectorControls from '../../inspector-controls';
 import ToggleControl from '../../inspector-controls/toggle-control';
 import BlockDescription from '../../block-description';
 
-const { children, query } = hpq;
+const { children, query } = source;
 
 registerBlockType( 'core/cover-text', {
 	title: __( 'Cover Text' ),

blocks/library/embed/index.js

@@ -16,12 +16,12 @@ import { addQueryArgs } from '@wordpress/url';
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlockType, query, createBlock } from '../../api';
+import { registerBlockType, source, createBlock } from '../../api';
 import Editable from '../../editable';
 import BlockControls from '../../block-controls';
 import BlockAlignmentToolbar from '../../block-alignment-toolbar';
 
-const { children } = query;
+const { children } = source;
 
 // These embeds do not work in sandboxes
 const HOSTS_NO_PREVIEWS = [ 'facebook.com' ];

blocks/library/freeform/index.js

@@ -7,10 +7,10 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlockType, query, setUnknownTypeHandlerName } from '../../api';
+import { registerBlockType, source, setUnknownTypeHandlerName } from '../../api';
 import OldEditor from './old-editor';
 
-const { prop } = query;
+const { prop } = source;
 
 registerBlockType( 'core/freeform', {
 	title: __( 'Classic Text' ),

blocks/library/heading/index.js

@@ -9,14 +9,14 @@ import { Toolbar } from '@wordpress/components';
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlockType, createBlock, query } from '../../api';
+import { registerBlockType, createBlock, source } from '../../api';
 import Editable from '../../editable';
 import BlockControls from '../../block-controls';
 import InspectorControls from '../../inspector-controls';
 import AlignmentToolbar from '../../alignment-toolbar';
 import BlockDescription from '../../block-description';
 
-const { children, prop } = query;
+const { children, prop } = source;
 
 registerBlockType( 'core/heading', {
 	title: __( 'Heading' ),
@@ -58,7 +58,7 @@ registerBlockType( 'core/heading', {
 			},
 			{
 				type: 'raw',
-				matcher: ( node ) => /H\d/.test( node.nodeName ),
+				source: ( node ) => /H\d/.test( node.nodeName ),
 				attributes: {
 					content: children( 'h1,h2,h3,h4,h5,h6' ),
 					nodeName: prop( 'h1,h2,h3,h4,h5,h6', 'nodeName' ),