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 798acf6575f82..cd110973b124f 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 6dc993739a279..ee478602fd1e9 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 ffc896ea4924a..b0def1aff4d08 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 c6340ff4f94bc..53b3d85e5dbd6 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 811b97fb436d1..a2843ecf6e3b4 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 a091ab08a8942..4a64fb0cc0585 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 40f279c02d726..f50004b2d363d 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 891034d3c3c27..5db58647c3988 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/children.js b/packages/blocks/src/api/test/children.js index dbc066e585850..8a57c6a71f3b5 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 3e355a884808b..84d7161659928 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,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 ); diff --git a/packages/blocks/src/api/test/matchers.js b/packages/blocks/src/api/test/matchers.js index 9f7fccefbe38e..2068ae18c6e06 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 8c627f95b3896..0c5269ad72323 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 f3aab4a89423e..a60776801eb33 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 c4baf9cf1186f..9ac2c197819ce 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": []