RichText state structure for value manipulation

docs/manifest.json

@@ -383,6 +383,12 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/element/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/escape-html",
+		"slug": "packages-escape-html",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/escape-html/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/hooks",
 		"slug": "packages-hooks",
@@ -467,6 +473,12 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/redux-routine/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/rich-text",
+		"slug": "packages-rich-text",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/rich-text/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/scripts",
 		"slug": "packages-scripts",

docs/reference/deprecated.md

@@ -1,5 +1,16 @@
 Gutenberg's deprecation policy is intended to support backwards-compatibility for two minor releases, when possible. The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.
 
+## 4.4.0
+
+- The block attribute sources `children` and `node` have been removed. Please use the `rich-text` source instead. See the core blocks for examples.
+- `wp.blocks.node.matcher` has been removed. Please use `wp.richTextValue.create` instead.
+- `wp.blocks.node.toHTML` has been removed. Please use `wp.richTextValue.toHTMLString` instead.
+- `wp.blocks.node.fromDOM` has been removed. Please use `wp.richTextValue.create` instead.
+- `wp.blocks.children.toHTML` has been removed. Please use `wp.richTextValue.toHTMLString` instead.
+- `wp.blocks.children.fromDOM` has been removed. Please use `wp.richTextValue.create` instead.
+- `wp.blocks.children.concat` has been removed. Please use `wp.richTextValue.concat` instead.
+- `wp.blocks.children.getChildrenArray` has been removed. Please use `wp.richTextValue.create` instead.
+
 ## 4.2.0
 
 - Writing resolvers as async generators has been removed. Use the controls plugin instead.

lib/client-assets.php

@@ -360,10 +360,24 @@ function gutenberg_register_scripts_and_styles() {
 	wp_register_script(
 		'wp-element',
 		gutenberg_url( 'build/element/index.js' ),
-		array( 'wp-polyfill', 'react', 'react-dom', 'lodash' ),
+		array( 'wp-polyfill', 'react', 'react-dom', 'lodash', 'wp-escape-html' ),
 		filemtime( gutenberg_dir_path() . 'build/element/index.js' ),
 		true
 	);
+	wp_register_script(
+		'wp-escape-html',
+		gutenberg_url( 'build/escape-html/index.js' ),
+		array( 'wp-polyfill' ),
+		filemtime( gutenberg_dir_path() . 'build/element/index.js' ),
+		true
+	);
+	wp_register_script(
+		'wp-rich-text',
+		gutenberg_url( 'build/rich-text/index.js' ),
+		array( 'wp-polyfill', 'wp-escape-html', 'lodash' ),
+		filemtime( gutenberg_dir_path() . 'build/rich-text/index.js' ),
+		true
+	);
 	wp_register_script(
 		'wp-components',
 		gutenberg_url( 'build/components/index.js' ),
@@ -383,6 +397,7 @@ function gutenberg_register_scripts_and_styles() {
 			'wp-keycodes',
 			'wp-polyfill',
 			'wp-url',
+			'wp-rich-text',
 		),
 		filemtime( gutenberg_dir_path() . 'build/components/index.js' ),
 		true
@@ -408,6 +423,7 @@ function gutenberg_register_scripts_and_styles() {
 			'wp-polyfill',
 			'wp-shortcode',
 			'lodash',
+			'wp-rich-text',
 		),
 		filemtime( gutenberg_dir_path() . 'build/blocks/index.js' ),
 		true
@@ -442,6 +458,7 @@ function gutenberg_register_scripts_and_styles() {
 			'wp-polyfill',
 			'wp-url',
 			'wp-viewport',
+			'wp-rich-text',
 		),
 		filemtime( gutenberg_dir_path() . 'build/block-library/index.js' ),
 		true
@@ -601,6 +618,7 @@ function gutenberg_register_scripts_and_styles() {
 			'wp-url',
 			'wp-viewport',
 			'wp-wordcount',
+			'wp-rich-text',
 		),
 		filemtime( gutenberg_dir_path() . 'build/editor/index.js' )
 	);

package.json

@@ -33,6 +33,7 @@
 		"@wordpress/dom-ready": "file:packages/dom-ready",
 		"@wordpress/editor": "file:packages/editor",
 		"@wordpress/element": "file:packages/element",
+		"@wordpress/escape-html": "file:packages/escape-html",
 		"@wordpress/hooks": "file:packages/hooks",
 		"@wordpress/html-entities": "file:packages/html-entities",
 		"@wordpress/i18n": "file:packages/i18n",
@@ -41,6 +42,7 @@
 		"@wordpress/nux": "file:packages/nux",
 		"@wordpress/plugins": "file:packages/plugins",
 		"@wordpress/redux-routine": "file:packages/redux-routine",
+		"@wordpress/rich-text": "file:packages/rich-text",
 		"@wordpress/shortcode": "file:packages/shortcode",
 		"@wordpress/token-list": "file:packages/token-list",
 		"@wordpress/url": "file:packages/url",

packages/block-library/src/audio/index.js

@@ -30,8 +30,7 @@ export const settings = {
 			attribute: 'src',
 		},
 		caption: {
-			type: 'array',
-			source: 'children',
+			source: 'rich-text',
 			selector: 'figcaption',
 		},
 		id: {

packages/block-library/src/button/index.js

@@ -32,8 +32,7 @@ const blockAttributes = {
 		attribute: 'title',
 	},
 	text: {
-		type: 'array',
-		source: 'children',
+		source: 'rich-text',
 		selector: 'a',
 	},
 	backgroundColor: {

packages/block-library/src/cover-image/index.js

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { isEmpty } from 'lodash';
 import classnames from 'classnames';
 
 /**
@@ -25,8 +24,7 @@ const validAlignments = [ 'left', 'center', 'right', 'wide', 'full' ];
 
 const blockAttributes = {
 	title: {
-		type: 'array',
-		source: 'children',
+		source: 'rich-text',
 		selector: 'p',
 	},
 	url: {
@@ -195,7 +193,7 @@ export const settings = {
 		);
 
 		if ( ! url ) {
-			const hasTitle = ! isEmpty( title );
+			const hasTitle = ! RichText.isEmpty( title );
 			const icon = hasTitle ? undefined : 'format-image';
 			const label = hasTitle ? (
 				<RichText
@@ -276,8 +274,7 @@ export const settings = {
 		attributes: {
 			...blockAttributes,
 			title: {
-				type: 'array',
-				source: 'children',
+				source: 'rich-text',
 				selector: 'h2',
 			},
 		},

packages/block-library/src/embed/index.js

@@ -371,10 +371,8 @@ const embedAttributes = {
 		type: 'string',
 	},
 	caption: {
-		type: 'array',
-		source: 'children',
+		source: 'rich-text',
 		selector: 'figcaption',
-		default: [],
 	},
 	type: {
 		type: 'string',

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

@@ -45,8 +45,7 @@ const blockAttributes = {
 				attribute: 'data-id',
 			},
 			caption: {
-				type: 'array',
-				source: 'children',
+				source: 'rich-text',
 				selector: 'figcaption',
 			},
 		},

packages/block-library/src/heading/index.js

@@ -12,9 +12,9 @@ import {
 	getPhrasingContentSchema,
 	getBlockAttributes,
 	getBlockType,
-	children,
 } from '@wordpress/blocks';
 import { RichText } from '@wordpress/editor';
+import { concat } from '@wordpress/rich-text';
 
 /**
  * Internal dependencies
@@ -39,8 +39,7 @@ const supports = {
 
 const schema = {
 	content: {
-		type: 'array',
-		source: 'children',
+		source: 'rich-text',
 		selector: 'h1,h2,h3,h4,h5,h6',
 	},
 	level: {
@@ -167,10 +166,7 @@ export const settings = {
 
 	merge( attributes, attributesToMerge ) {
 		return {
-			content: children.concat(
-				attributes.content,
-				attributesToMerge.content
-			),
+			content: concat( attributes.content, attributesToMerge.content ),
 		};
 	},
 

packages/block-library/src/image/index.js

@@ -39,8 +39,7 @@ const blockAttributes = {
 		default: '',
 	},
 	caption: {
-		type: 'array',
-		source: 'children',
+		source: 'rich-text',
 		selector: 'figcaption',
 	},
 	href: {