From 7008516aaf4611fcda24214155e133503bff0b24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ella=20van=C2=A0Durpe?= Date: Mon, 19 Sep 2022 16:15:02 +0300 Subject: [PATCH 1/2] blocks: officially deprecated the children and node matchers --- .../block-controls-toolbar-and-sidebar.md | 8 ++--- .../block-supports-in-static-blocks.md | 8 ++--- ...roducing-attributes-and-editable-fields.md | 8 ++--- .../src/components/rich-text/index.js | 14 ++++++++ .../block-library/src/gallery/deprecated.js | 8 ++--- packages/blocks/CHANGELOG.md | 1 + packages/blocks/src/api/children.js | 35 +++++++++++++++++++ packages/blocks/src/api/node.js | 32 +++++++++++++++++ packages/blocks/src/api/test/factory.js | 18 +++++----- 9 files changed, 107 insertions(+), 25 deletions(-) diff --git a/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md b/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md index 798acf6575f826..cd110973b124f2 100644 --- a/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md +++ b/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: { diff --git a/docs/how-to-guides/block-tutorial/block-supports-in-static-blocks.md b/docs/how-to-guides/block-tutorial/block-supports-in-static-blocks.md index 6dc993739a2793..ee478602fd1e9b 100644 --- a/docs/how-to-guides/block-tutorial/block-supports-in-static-blocks.md +++ b/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', }, }, diff --git a/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md b/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md index ffc896ea4924ac..b0def1aff4d08e 100644 --- a/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md +++ b/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', }, }, diff --git a/packages/block-editor/src/components/rich-text/index.js b/packages/block-editor/src/components/rich-text/index.js index c6340ff4f94bc0..53b3d85e5dbd6e 100644 --- a/packages/block-editor/src/components/rich-text/index.js +++ b/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 ); } diff --git a/packages/block-library/src/gallery/deprecated.js b/packages/block-library/src/gallery/deprecated.js index 811b97fb436d12..a2843ecf6e3b42 100644 --- a/packages/block-library/src/gallery/deprecated.js +++ b/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', }, }, diff --git a/packages/blocks/CHANGELOG.md b/packages/blocks/CHANGELOG.md index a091ab08a89429..4a64fb0cc0585b 100644 --- a/packages/blocks/CHANGELOG.md +++ b/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) diff --git a/packages/blocks/src/api/children.js b/packages/blocks/src/api/children.js index 40f279c02d7268..f50004b2d363de 100644 --- a/packages/blocks/src/api/children.js +++ b/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} 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; diff --git a/packages/blocks/src/api/node.js b/packages/blocks/src/api/node.js index 891034d3c3c279..5db58647c39885 100644 --- a/packages/blocks/src/api/node.js +++ b/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; diff --git a/packages/blocks/src/api/test/factory.js b/packages/blocks/src/api/test/factory.js index 3e355a884808ba..976a6d6a784713 100644 --- a/packages/blocks/src/api/test/factory.js +++ b/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,9 @@ describe( 'block factory', () => { includesFalseyDefault: 0, align: 'left', isDifferent: true, - content: [], - defaultContent: [ 'test' ], - unknownDefaultContent: [], + content: '', + defaultContent: 'test', + unknownDefaultContent: '', htmlContent: 'test', } ); expect( clonedBlock.innerBlocks ).toHaveLength( 1 ); From 7069bdb555daf22e39c5ebd6447cc3b0bcefc48c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ella=20van=C2=A0Durpe?= Date: Mon, 19 Sep 2022 20:59:12 +0300 Subject: [PATCH 2/2] Fix unit tests --- packages/blocks/src/api/test/children.js | 3 +++ packages/blocks/src/api/test/factory.js | 3 +-- packages/blocks/src/api/test/matchers.js | 3 +++ packages/blocks/src/api/test/node.js | 3 +++ .../fixtures/blocks/core__gallery__deprecated-2.json | 4 ++-- .../fixtures/blocks/core__gallery__deprecated-3.json | 4 ++-- 6 files changed, 14 insertions(+), 6 deletions(-) diff --git a/packages/blocks/src/api/test/children.js b/packages/blocks/src/api/test/children.js index dbc066e585850c..8a57c6a71f3b50 100644 --- a/packages/blocks/src/api/test/children.js +++ b/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 test!' ); } ); } ); @@ -121,6 +123,7 @@ describe( 'fromDOM', () => { const blockNode = fromDOM( node.childNodes ); + expect( console ).toHaveWarned(); expect( blockNode ).toEqual( [ 'This ', { diff --git a/packages/blocks/src/api/test/factory.js b/packages/blocks/src/api/test/factory.js index 976a6d6a784713..84d7161659928a 100644 --- a/packages/blocks/src/api/test/factory.js +++ b/packages/blocks/src/api/test/factory.js @@ -340,9 +340,8 @@ describe( 'block factory', () => { includesFalseyDefault: 0, align: 'left', isDifferent: true, - content: '', defaultContent: 'test', - unknownDefaultContent: '', + unknownDefaultContent: 1, htmlContent: 'test', } ); expect( clonedBlock.innerBlocks ).toHaveLength( 1 ); diff --git a/packages/blocks/src/api/test/matchers.js b/packages/blocks/src/api/test/matchers.js index 9f7fccefbe38e5..2068ae18c6e066 100644 --- a/packages/blocks/src/api/test/matchers.js +++ b/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', () => { '

A delicious sundae dessert

'; 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' ); } ); diff --git a/packages/blocks/src/api/test/node.js b/packages/blocks/src/api/test/node.js index 8c627f95b3896d..0c5269ad723239 100644 --- a/packages/blocks/src/api/test/node.js +++ b/packages/blocks/src/api/test/node.js @@ -30,6 +30,7 @@ describe( 'toHTML', () => { const html = toHTML( blockNode ); + expect( console ).toHaveWarned(); expect( html ).toBe( 'This is a test' ); @@ -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: { diff --git a/test/integration/fixtures/blocks/core__gallery__deprecated-2.json b/test/integration/fixtures/blocks/core__gallery__deprecated-2.json index f3aab4a89423e2..a60776801eb337 100644 --- a/test/integration/fixtures/blocks/core__gallery__deprecated-2.json +++ b/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" }, diff --git a/test/integration/fixtures/blocks/core__gallery__deprecated-3.json b/test/integration/fixtures/blocks/core__gallery__deprecated-3.json index c4baf9cf1186f6..9ac2c197819ce5 100644 --- a/test/integration/fixtures/blocks/core__gallery__deprecated-3.json +++ b/test/integration/fixtures/blocks/core__gallery__deprecated-3.json @@ -15,7 +15,7 @@ "attributes": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==", "alt": "title", - "caption": [], + "caption": "", "linkDestination": "none" }, "innerBlocks": [] @@ -26,7 +26,7 @@ "attributes": { "url": "data:image/jpeg;base64,/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEAAD8A0s8g/9k=", "alt": "title", - "caption": [], + "caption": "", "linkDestination": "none" }, "innerBlocks": []