Block API: Stub default attributes, keywords values for block type re…

…gistration

packages/blocks/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Master
 
+### Improvements
+
+- Omitting `attributes` or `keywords` settings will now stub default values (an empty object or empty array, respectively).
+
 ### Bug Fixes
 
 - The `'blocks.registerBlockType'` filter is now applied to each of a block's deprecated settings as well as the block's main settings. Ensures `supports` settings like `anchor` work for deprecations.

packages/blocks/src/api/registration.js

@@ -21,30 +21,72 @@ import { select, dispatch } from '@wordpress/data';
  */
 import { isValidIcon, normalizeIconObject } from './utils';
 
+/**
+ * Render behavior of a block type icon; one of a Dashicon slug, an element,
+ * or a component.
+ *
+ * @typedef {(string|WPElement|WPComponent)} WPBlockTypeIconRender
+ *
+ * @see https://developer.wordpress.org/resource/dashicons/
+ */
+
+/**
+ * An object describing a normalized block type icon.
+ *
+ * @typedef {WPBlockTypeIconDescriptor}
+ *
+ * @property {WPBlockTypeIconRender} src         Render behavior of the icon,
+ *                                               one of a Dashicon slug, an
+ *                                               element, or a component.
+ * @property {string}                background  Optimal background hex string
+ *                                               color when displaying icon.
+ * @property {string}                foreground  Optimal foreground hex string
+ *                                               color when displaying icon.
+ * @property {string}                shadowColor Optimal shadow hex string
+ *                                               color when displaying icon.
+ */
+
+/**
+ * Value to use to render the icon for a block type in an editor interface,
+ * either a Dashicon slug, an element, a component, or an object describing
+ * the icon.
+ *
+ * @typedef {(WPBlockTypeIconDescriptor|WPBlockTypeIconRender)} WPBlockTypeIcon
+ */
+
 /**
  * Defined behavior of a block type.
  *
  * @typedef {WPBlockType}
  *
- * @property {string}                    name       Block's namespaced name.
- * @property {string}                    title      Human-readable label for a block.
- *                                                  Shown in the block inserter.
- * @property {string}                    category   Category classification of block,
- *                                                  impacting where block is shown in
- *                                                  inserter results.
- * @property {(Object|string|WPElement)} icon       Slug of the Dashicon to be shown
- *                                                  as the icon for the block in the
- *                                                  inserter, or element or an object describing the icon.
- * @property {?string[]}                 keywords   Additional keywords to produce
- *                                                  block as inserter search result.
- * @property {?Object}                   attributes Block attributes.
- * @property {?Function}                 save       Serialize behavior of a block,
- *                                                  returning an element describing
- *                                                  structure of the block's post
- *                                                  content markup.
- * @property {WPComponent}               edit       Component rendering element to be
- *                                                  interacted with in an editor.
+ * @property {string}           name       Block type's namespaced name.
+ * @property {string}           title      Human-readable block type label.
+ * @property {string}           category   Block type category classification,
+ *                                         used in search interfaces to arrange
+ *                                         block types by category.
+ * @property {?WPBlockTypeIcon} icon       Block type icon.
+ * @property {?string[]}        keywords   Additional keywords to produce block
+ *                                         type as result in search interfaces.
+ * @property {?Object}          attributes Block type attributes.
+ * @property {?WPComponent}     save       Optional component describing
+ *                                         serialized markup structure of a
+ *                                         block type.
+ * @property {WPComponent}      edit       Component rendering an element to
+ *                                         manipulate the attributes of a block
+ *                                         in the context of an editor.
+ */
+
+/**
+ * Default values to assign for omitted optional block type settings.
+ *
+ * @type {Object}
  */
+const DEFAULT_BLOCK_TYPE_SETTINGS = {
+	icon: 'block-default',
+	attributes: {},
+	keywords: [],
+	save: () => null,
+};
 
 let serverSideBlockDefinitions = {};
 
@@ -74,7 +116,7 @@ export function unstable__bootstrapServerSideBlockDefinitions( definitions ) { /
 export function registerBlockType( name, settings ) {
 	settings = {
 		name,
-		save: () => null,
+		...DEFAULT_BLOCK_TYPE_SETTINGS,
 		...get( serverSideBlockDefinitions, name ),
 		...settings,
 	};

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

@@ -95,6 +95,8 @@ describe( 'blocks', () => {
 				icon: {
 					src: 'block-default',
 				},
+				attributes: {},
+				keywords: [],
 				save: noop,
 				category: 'common',
 				title: 'block title',
@@ -111,6 +113,8 @@ describe( 'blocks', () => {
 		it( 'should reject blocks with invalid save function', () => {
 			const block = registerBlockType( 'my-plugin/fancy-block-5', {
 				...defaultBlockSettings,
+				attributes: {},
+				keywords: [],
 				save: 'invalid',
 			} );
 			expect( console ).toHaveErroredWith( 'The "save" property must be a valid function.' );
@@ -159,6 +163,25 @@ describe( 'blocks', () => {
 			expect( block ).toBeUndefined();
 		} );
 
+		it( 'should assign default settings', () => {
+			registerBlockType( 'core/test-block-with-defaults', {
+				title: 'block title',
+				category: 'common',
+			} );
+
+			expect( getBlockType( 'core/test-block-with-defaults' ) ).toEqual( {
+				name: 'core/test-block-with-defaults',
+				title: 'block title',
+				category: 'common',
+				icon: {
+					src: 'block-default',
+				},
+				attributes: {},
+				keywords: [],
+				save: expect.any( Function ),
+			} );
+		} );
+
 		it( 'should default to browser-initialized global attributes', () => {
 			const attributes = { ok: { type: 'boolean' } };
 			unstable__bootstrapServerSideBlockDefinitions( {
@@ -181,6 +204,7 @@ describe( 'blocks', () => {
 						type: 'boolean',
 					},
 				},
+				keywords: [],
 			} );
 		} );
 
@@ -218,6 +242,8 @@ describe( 'blocks', () => {
 							fill="red" stroke="blue" strokeWidth="10" />
 					</svg> ),
 				},
+				attributes: {},
+				keywords: [],
 			} );
 		} );
 
@@ -237,6 +263,8 @@ describe( 'blocks', () => {
 				icon: {
 					src: 'foo',
 				},
+				attributes: {},
+				keywords: [],
 			} );
 		} );
 
@@ -262,6 +290,8 @@ describe( 'blocks', () => {
 				icon: {
 					src: MyTestIcon,
 				},
+				attributes: {},
+				keywords: [],
 			} );
 		} );
 
@@ -293,6 +323,8 @@ describe( 'blocks', () => {
 							fill="red" stroke="blue" strokeWidth="10" />
 					</svg> ),
 				},
+				attributes: {},
+				keywords: [],
 			} );
 		} );
 
@@ -309,6 +341,8 @@ describe( 'blocks', () => {
 				icon: {
 					src: 'block-default',
 				},
+				attributes: {},
+				keywords: [],
 			} );
 		} );
 
@@ -394,6 +428,8 @@ describe( 'blocks', () => {
 					icon: {
 						src: 'block-default',
 					},
+					attributes: {},
+					keywords: [],
 				},
 			] );
 			const oldBlock = unregisterBlockType( 'core/test-block' );
@@ -406,6 +442,8 @@ describe( 'blocks', () => {
 				icon: {
 					src: 'block-default',
 				},
+				attributes: {},
+				keywords: [],
 			} );
 			expect( getBlockTypes() ).toEqual( [] );
 		} );
@@ -478,6 +516,8 @@ describe( 'blocks', () => {
 				icon: {
 					src: 'block-default',
 				},
+				attributes: {},
+				keywords: [],
 			} );
 		} );
 
@@ -493,6 +533,8 @@ describe( 'blocks', () => {
 				icon: {
 					src: 'block-default',
 				},
+				attributes: {},
+				keywords: [],
 			} );
 		} );
 	} );
@@ -515,6 +557,8 @@ describe( 'blocks', () => {
 					icon: {
 						src: 'block-default',
 					},
+					attributes: {},
+					keywords: [],
 				},
 				{
 					name: 'core/test-block-with-settings',
@@ -525,6 +569,8 @@ describe( 'blocks', () => {
 					icon: {
 						src: 'block-default',
 					},
+					attributes: {},
+					keywords: [],
 				},
 			] );
 		} );

packages/blocks/src/api/utils.js

@@ -77,17 +77,13 @@ export function isValidIcon( icon ) {
  * and returns a new icon object that is normalized so we can rely on just on possible icon structure
  * in the codebase.
  *
- * @param {(Object|string|WPElement)} icon  Slug of the Dashicon to be shown
- *                                          as the icon for the block in the
- *                                          inserter, or element or an object describing the icon.
+ * @param {WPBlockTypeIconRender} icon Render behavior of a block type icon;
+ *                                     one of a Dashicon slug, an element, or a
+ *                                     component.
  *
- * @return {Object} Object describing the icon.
+ * @return {WPBlockTypeIconDescriptor} Object describing the icon.
  */
 export function normalizeIconObject( icon ) {
-	if ( ! icon ) {
-		icon = 'block-default';
-	}
-
 	if ( isValidIcon( icon ) ) {
 		return { src: icon };
 	}