Blocks: officially deprecated the children and node matchers

docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md

@@ -30,8 +30,8 @@ registerBlockType( 'gutenberg-examples/example-04-controls-esnext', {
 	category: 'design',
 	attributes: {
 		content: {
-			type: 'array',
-			source: 'children',
+			type: 'string',
+			source: 'html',
 			selector: 'p',
 		},
 		alignment: {
@@ -109,8 +109,8 @@ registerBlockType( 'gutenberg-examples/example-04-controls-esnext', {
 
 		attributes: {
 			content: {
-				type: 'array',
-				source: 'children',
+				type: 'string',
+				source: 'html',
 				selector: 'p',
 			},
 			alignment: {

docs/how-to-guides/block-tutorial/block-supports-in-static-blocks.md

@@ -22,8 +22,8 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', {
 	category: 'design',
 	attributes: {
 		content: {
-			type: 'array',
-			source: 'children',
+			type: 'string',
+			source: 'html',
 			selector: 'p',
 		},
 	},
@@ -80,8 +80,8 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', {
 
 		attributes: {
 			content: {
-				type: 'array',
-				source: 'children',
+				type: 'string',
+				source: 'html',
 				selector: 'p',
 			},
 		},

docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md

@@ -66,8 +66,8 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', {
 	category: 'design',
 	attributes: {
 		content: {
-			type: 'array',
-			source: 'children',
+			type: 'string',
+			source: 'html',
 			selector: 'p',
 		},
 	},
@@ -124,8 +124,8 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', {
 
 		attributes: {
 			content: {
-				type: 'array',
-				source: 'children',
+				type: 'string',
+				source: 'html',
 				selector: 'p',
 			},
 		},

packages/block-editor/src/components/rich-text/index.js

@@ -173,6 +173,13 @@ function RichTextWrapper(
 
 	// Handle deprecated format.
 	if ( Array.isArray( originalValue ) ) {
+		deprecated( 'wp.blockEditor.RichText value prop as children type', {
+			since: '6.1',
+			version: '6.3',
+			alternative: 'value prop as string',
+			link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+		} );
+
 		adjustedValue = childrenSource.toHTML( originalValue );
 		adjustedOnChange = ( newValue ) =>
 			originalOnChange(
@@ -436,6 +443,13 @@ ForwardedRichTextContainer.Content = ( {
 } ) => {
 	// Handle deprecated `children` and `node` sources.
 	if ( Array.isArray( value ) ) {
+		deprecated( 'wp.blockEditor.RichText value prop as children type', {
+			since: '6.1',
+			version: '6.3',
+			alternative: 'value prop as string',
+			link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+		} );
+
 		value = childrenSource.toHTML( value );
 	}
 

packages/block-library/src/gallery/deprecated.js

@@ -659,8 +659,8 @@ const v3 = {
 					attribute: 'data-link',
 				},
 				caption: {
-					type: 'array',
-					source: 'children',
+					type: 'string',
+					source: 'html',
 					selector: 'figcaption',
 				},
 			},
@@ -779,8 +779,8 @@ const v2 = {
 					attribute: 'data-link',
 				},
 				caption: {
-					type: 'array',
-					source: 'children',
+					type: 'string',
+					source: 'html',
 					selector: 'figcaption',
 				},
 			},

packages/blocks/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- The block attribute sources `children` and `node` have been deprecated. Please use the `html` source instead. See https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/ and the core blocks for examples.
 ## 11.16.0 (2022-09-13)
 
 ## 11.15.0 (2022-08-24)

packages/blocks/src/api/children.js

@@ -7,6 +7,7 @@ import { castArray } from 'lodash';
  * WordPress dependencies
  */
 import { renderToString } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -44,6 +45,12 @@ export function getSerializeCapableElement( children ) {
  * @return {Array<WPBlockNode>} An array of individual block nodes.
  */
 function getChildrenArray( children ) {
+	deprecated( 'wp.blocks.children.getChildrenArray', {
+		since: '6.1',
+		version: '6.3',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	// The fact that block children are compatible with the element serializer
 	// is merely an implementation detail that currently serves to be true, but
 	// should not be mistaken as being a guarantee on the external API.
@@ -59,6 +66,13 @@ function getChildrenArray( children ) {
  * @return {WPBlockChildren} Concatenated block node.
  */
 export function concat( ...blockNodes ) {
+	deprecated( 'wp.blocks.children.concat', {
+		since: '6.1',
+		version: '6.3',
+		alternative: 'wp.richText.concat',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	const result = [];
 	for ( let i = 0; i < blockNodes.length; i++ ) {
 		const blockNode = castArray( blockNodes[ i ] );
@@ -88,6 +102,13 @@ export function concat( ...blockNodes ) {
  * @return {WPBlockChildren} Block children equivalent to DOM nodes.
  */
 export function fromDOM( domNodes ) {
+	deprecated( 'wp.blocks.children.fromDOM', {
+		since: '6.1',
+		version: '6.3',
+		alternative: 'wp.richText.create',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	const result = [];
 	for ( let i = 0; i < domNodes.length; i++ ) {
 		try {
@@ -108,6 +129,13 @@ export function fromDOM( domNodes ) {
  * @return {string} String HTML representation of block node.
  */
 export function toHTML( children ) {
+	deprecated( 'wp.blocks.children.toHTML', {
+		since: '6.1',
+		version: '6.3',
+		alternative: 'wp.richText.toHTMLString',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	const element = getSerializeCapableElement( children );
 
 	return renderToString( element );
@@ -122,6 +150,13 @@ export function toHTML( children ) {
  * @return {Function} hpq matcher.
  */
 export function matcher( selector ) {
+	deprecated( 'wp.blocks.children.matcher', {
+		since: '6.1',
+		version: '6.3',
+		alternative: 'html source',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	return ( domNode ) => {
 		let match = domNode;
 

packages/blocks/src/api/node.js

@@ -1,3 +1,8 @@
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+
 /**
  * Internal dependencies
  */
@@ -24,6 +29,12 @@ import * as children from './children';
  * @return {boolean} Whether node is of intended type.
  */
 function isNodeOfType( node, type ) {
+	deprecated( 'wp.blocks.node.isNodeOfType', {
+		since: '6.1',
+		version: '6.3',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	return node && node.type === type;
 }
 
@@ -58,6 +69,13 @@ export function getNamedNodeMapAsObject( nodeMap ) {
  * @return {WPBlockNode} Block node equivalent to DOM node.
  */
 export function fromDOM( domNode ) {
+	deprecated( 'wp.blocks.node.fromDOM', {
+		since: '6.1',
+		version: '6.3',
+		alternative: 'wp.richText.create',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	if ( domNode.nodeType === domNode.TEXT_NODE ) {
 		return domNode.nodeValue;
 	}
@@ -86,6 +104,13 @@ export function fromDOM( domNode ) {
  * @return {string} String HTML representation of block node.
  */
 export function toHTML( node ) {
+	deprecated( 'wp.blocks.node.toHTML', {
+		since: '6.1',
+		version: '6.3',
+		alternative: 'wp.richText.toHTMLString',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	return children.toHTML( [ node ] );
 }
 
@@ -98,6 +123,13 @@ export function toHTML( node ) {
  * @return {Function} hpq matcher.
  */
 export function matcher( selector ) {
+	deprecated( 'wp.blocks.node.matcher', {
+		since: '6.1',
+		version: '6.3',
+		alternative: 'html source',
+		link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields/',
+	} );
+
 	return ( domNode ) => {
 		let match = domNode;
 

packages/blocks/src/api/test/children.js

@@ -57,6 +57,7 @@ describe( 'concat', () => {
 			}
 		);
 
+		expect( console ).toHaveWarned();
 		expect( result ).toEqual( [
 			{
 				type: 'strong',
@@ -109,6 +110,7 @@ describe( 'toHTML', () => {
 
 		const html = toHTML( children );
 
+		expect( console ).toHaveWarned();
 		expect( html ).toBe( 'This is a <strong>test</strong>!' );
 	} );
 } );
@@ -121,6 +123,7 @@ describe( 'fromDOM', () => {
 
 		const blockNode = fromDOM( node.childNodes );
 
+		expect( console ).toHaveWarned();
 		expect( blockNode ).toEqual( [
 			'This ',
 			{

packages/blocks/src/api/test/factory.js

@@ -302,17 +302,17 @@ describe( 'block factory', () => {
 						default: 0,
 					},
 					content: {
-						type: 'array',
-						source: 'children',
+						type: 'string',
+						source: 'html',
 					},
 					defaultContent: {
-						type: 'array',
-						source: 'children',
+						type: 'string',
+						source: 'html',
 						default: 'test',
 					},
 					unknownDefaultContent: {
-						type: 'array',
-						source: 'children',
+						type: 'string',
+						source: 'html',
 						default: 1,
 					},
 					htmlContent: {
@@ -340,9 +340,8 @@ describe( 'block factory', () => {
 				includesFalseyDefault: 0,
 				align: 'left',
 				isDifferent: true,
-				content: [],
-				defaultContent: [ 'test' ],
-				unknownDefaultContent: [],
+				defaultContent: 'test',
+				unknownDefaultContent: 1,
 				htmlContent: 'test',
 			} );
 			expect( clonedBlock.innerBlocks ).toHaveLength( 1 );

packages/blocks/src/api/test/matchers.js

@@ -18,6 +18,7 @@ describe( 'matchers', () => {
 		it( 'should return a source function', () => {
 			const source = sources.children();
 
+			expect( console ).toHaveWarned();
 			expect( typeof source ).toBe( 'function' );
 		} );
 
@@ -28,6 +29,7 @@ describe( 'matchers', () => {
 				'<blockquote><p>A delicious sundae dessert</p></blockquote>';
 			const match = parse( html, sources.children() );
 
+			expect( console ).toHaveWarned();
 			expect( renderToString( match ) ).toBe( html );
 		} );
 	} );
@@ -36,6 +38,7 @@ describe( 'matchers', () => {
 		it( 'should return a source function', () => {
 			const source = sources.node();
 
+			expect( console ).toHaveWarned();
 			expect( typeof source ).toBe( 'function' );
 		} );
 

packages/blocks/src/api/test/node.js

@@ -30,6 +30,7 @@ describe( 'toHTML', () => {
 
 		const html = toHTML( blockNode );
 
+		expect( console ).toHaveWarned();
 		expect( html ).toBe(
 			'<strong class="is-extra-strong">This is a test</strong>'
 		);
@@ -42,6 +43,7 @@ describe( 'fromDOM', () => {
 
 		const blockNode = fromDOM( node );
 
+		expect( console ).toHaveWarned();
 		expect( blockNode ).toBe( 'Hello world' );
 	} );
 
@@ -58,6 +60,7 @@ describe( 'fromDOM', () => {
 
 		const blockNode = fromDOM( node );
 
+		expect( console ).toHaveWarned();
 		expect( blockNode ).toEqual( {
 			type: 'strong',
 			props: {

test/integration/fixtures/blocks/core__gallery__deprecated-2.json

@@ -16,7 +16,7 @@
 				"attributes": {
 					"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==",
 					"alt": "title",
-					"caption": [],
+					"caption": "",
 					"id": 1,
 					"linkDestination": "none"
 				},
@@ -28,7 +28,7 @@
 				"attributes": {
 					"url": "data:image/jpeg;base64,/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEAAD8A0s8g/9k=",
 					"alt": "title",
-					"caption": [],
+					"caption": "",
 					"id": 2,
 					"linkDestination": "none"
 				},