Block API: Ensure backwards compatibility for block matchers

blocks/api/index.js

@@ -15,3 +15,7 @@ export {
 	getBlockTypes,
 	hasBlockSupport,
 } from './registration';
+
+// Deprecated matchers
+import * as source from './source';
+export { source };

blocks/api/matchers.js

@@ -0,0 +1,38 @@
+/**
+ * WordPress dependencies
+ */
+import { createElement } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import { nodeListToReact, nodeToReact } from 'dom-react';
+export { attr, prop, html, text, query } from 'hpq';
+
+export const children = ( selector ) => {
+	return ( domNode ) => {
+		let match = domNode;
+
+		if ( selector ) {
+			match = domNode.querySelector( selector );
+		}
+
+		if ( match ) {
+			return nodeListToReact( match.childNodes || [], createElement );
+		}
+
+		return [];
+	};
+};
+
+export const node = ( selector ) => {
+	return ( domNode ) => {
+		let match = domNode;
+
+		if ( selector ) {
+			match = domNode.querySelector( selector );
+		}
+
+		return nodeToReact( match, createElement );
+	};
+};

blocks/api/parser.js

@@ -12,7 +12,7 @@ import { getBlockType, getUnknownTypeHandlerName } from './registration';
 import { createBlock } from './factory';
 import { isValidBlock } from './validation';
 import { getCommentDelimitedContent } from './serializer';
-import { attr, prop, html, text, query, node, children } from './source';
+import { attr, prop, html, text, query, node, children } from './matchers';
 
 /**
  * Returns value coerced to the specified JSON schema type string

blocks/api/registration.js

@@ -3,7 +3,7 @@
 /**
  * External dependencies
  */
-import { get, isFunction, some } from 'lodash';
+import { get, isFunction, some, mapValues } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -119,6 +119,17 @@ export function registerBlockType( name, settings ) {
 		...settings,
 	};
 
+	// Resolve deprecated attributes
+	settings.attributes = mapValues( settings.attributes, ( attribute ) => {
+		if ( isFunction( attribute.source ) ) {
+			return {
+				...attribute,
+				...attribute.source(),
+			};
+		}
+		return attribute;
+	} );
+
 	settings = applyFilters( 'registerBlockType', settings, name );
 
 	return blocks[ name ] = settings;

blocks/api/source.js

@@ -1,38 +1,66 @@
-/**
- * WordPress dependencies
- */
-import { createElement } from '@wordpress/element';
+function warnAboutDeprecatedMatcher() {
+	// eslint-disable-next-line no-console
+	console.warn(
+		'Attributes matchers are deprecated and they will be removed in a future version of Gutenberg. ' +
+		'Please update your attributes definition https://wordpress.org/gutenberg/handbook/reference/attributes/'
+	);
+}
 
-/**
- * External dependencies
- */
-import { nodeListToReact, nodeToReact } from 'dom-react';
-export { attr, prop, html, text, query } from 'hpq';
-
-export const children = ( selector ) => {
-	return ( domNode ) => {
-		let match = domNode;
+export const attr = ( selector, attribute ) => () => {
+	warnAboutDeprecatedMatcher();
+	return {
+		source: 'attribute',
+		attribute: attribute === undefined ? selector : attribute,
+		selector: attribute === undefined ? undefined : selector,
+	};
+};
 
-		if ( selector ) {
-			match = domNode.querySelector( selector );
-		}
+export const prop = ( selector, property ) => () => {
+	warnAboutDeprecatedMatcher();
+	return {
+		source: 'property',
+		property: property === undefined ? selector : property,
+		selector: property === undefined ? undefined : selector,
+	};
+};
 
-		if ( match ) {
-			return nodeListToReact( match.childNodes || [], createElement );
-		}
+export const html = ( selector ) => () => {
+	warnAboutDeprecatedMatcher();
+	return {
+		source: 'html',
+		selector,
+	};
+};
 
-		return [];
+export const text = ( selector ) => () => {
+	warnAboutDeprecatedMatcher();
+	return {
+		source: 'text',
+		selector,
 	};
 };
 
-export const node = ( selector ) => {
-	return ( domNode ) => {
-		let match = domNode;
+export const query = ( selector, subMatchers ) => () => {
+	warnAboutDeprecatedMatcher();
+	return {
+		source: 'query',
+		selector,
+		query: subMatchers,
+	};
+};
 
-		if ( selector ) {
-			match = domNode.querySelector( selector );
-		}
+export const children = ( selector ) => () => {
+	warnAboutDeprecatedMatcher();
+	return {
+		source: 'children',
+		selector,
+	};
+};
 
-		return nodeToReact( match, createElement );
+export const node = ( selector ) => () => {
+	warnAboutDeprecatedMatcher();
+	return {
+		source: 'node',
+		selector,
 	};
 };

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

@@ -11,9 +11,9 @@ import { renderToString } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import * as sources from '../source';
+import * as sources from '../matchers';
 
-describe( 'sources', () => {
+describe( 'matchers', () => {
 	describe( 'children()', () => {
 		it( 'should return a source function', () => {
 			const source = sources.children();

blocks/library/button/index.js

@@ -156,6 +156,7 @@ class ButtonBlock extends Component {
 			</span>,
 			focus && (
 				<form
+					key="form-link"
 					className="blocks-button__inline-link"
 					onSubmit={ ( event ) => event.preventDefault() }>
 					<Dashicon icon="admin-links" />