@wordpress/blocks: Register block from metadata

types/wordpress__blocks/api/registration.d.ts

@@ -117,15 +117,19 @@ export function registerBlockStyle(blockName: string, styleVariation: BlockStyle
  * behavior. Once registered, the block is made available as an option to any
  * editor interface where blocks are implemented.
  *
- * @param name - Block name.
+ * @param blockNameOrMetadata - Block type name or its metadata.
  * @param settings - Block settings.
  *
  * @returns The block if it has been successfully registered, otherwise `undefined`.
  */
-export function registerBlockType<T extends Record<string, any> = {}>(
+export function registerBlockType<TAttributes extends Record<string, any> = {}>(
+    metadata: BlockConfiguration<TAttributes>,
+    settings?: BlockConfiguration<TAttributes>,
+): Block<TAttributes> | undefined;
+export function registerBlockType<TAttributes extends Record<string, any> = {}>(
     name: string,
-    settings: BlockConfiguration<T>
-): Block<T> | undefined;
+    settings: BlockConfiguration<TAttributes>,
+): Block<TAttributes> | undefined;
 
 /**
  * Assigns the default block name.

types/wordpress__blocks/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for @wordpress/blocks 9.0
+// Type definitions for @wordpress/blocks 9.1
 // Project: https://github.com/WordPress/gutenberg/tree/master/packages/blocks/README.md
 // Definitions by: Derek Sifford <https://github.com/dsifford>
 //                 Jon Surrell <https://github.com/sirreal>
@@ -46,7 +46,25 @@ export interface BlockStyle {
     readonly isDefault?: boolean | undefined;
 }
 
+/**
+ * Internal type for the innerBlocks property inside of the example
+ *
+ * @internal
+ * @see Block.example
+ * @see {@link https://github.com/DefinitelyTyped/DefinitelyTyped/pull/55245#discussion_r692208988}
+ */
+type BlockExampleInnerBlock = Partial<Block> &
+    Pick<Block, 'name' | 'attributes'> & {
+        innerBlocks?: ReadonlyArray<BlockExampleInnerBlock>;
+    };
+
 export interface Block<T extends Record<string, any> = {}> {
+    /**
+     * The version of the Block API used by the block.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#api-version}
+     */
+    readonly apiVersion?: number;
     /**
      * Attributes for the block.
      */
@@ -70,6 +88,26 @@ export interface Block<T extends Record<string, any> = {}> {
      * Component to render in the editor.
      */
     readonly edit?: ComponentType<BlockEditProps<T>> | undefined;
+    /**
+     * Block type editor script definition.
+     * It will only be enqueued in the context of the editor.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-script}
+     */
+    readonly editorScript?: string;
+    /**
+     * Block type editor style definition.
+     * It will only be enqueued in the context of the editor.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-style}
+     */
+    readonly editorStyle?: string;
+    /**
+     * It provides structured example data for the block.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#example}
+     */
+    readonly example?: Readonly<Partial<Block> & { innerBlocks?: ReadonlyArray<BlockExampleInnerBlock> }>;
     /**
      * Icon for the block.
      */
@@ -83,6 +121,14 @@ export interface Block<T extends Record<string, any> = {}> {
      * nested within the specified blocks.
      */
     readonly parent?: readonly string[] | undefined;
+    /**
+     * Context provided for available access by descendants of blocks of this
+     * type, in the form of an object which maps a context name to one of the
+     * block’s own attribute.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#provides-context}
+     */
+    readonly providesContext?: Record<string, keyof T>;
     /**
      * This is set internally when registering the type.
      */
@@ -91,6 +137,21 @@ export interface Block<T extends Record<string, any> = {}> {
      * Component to render on the frontend.
      */
     readonly save: ComponentType<BlockSaveProps<T>>;
+    /**
+     * Block type frontend script definition.
+     * It will be enqueued both in the editor and when viewing the content on
+     * the front of the site.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#script}
+     */
+    readonly script?: string;
+    /**
+     * Block type editor style definition.
+     * It will only be enqueued in the context of the editor.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style}
+     */
+    readonly style?: string;
     /**
      * Block styles.
      *
@@ -101,6 +162,12 @@ export interface Block<T extends Record<string, any> = {}> {
      * Optional block extended support features.
      */
     readonly supports?: BlockSupports | undefined;
+    /**
+     * The gettext text domain of the plugin/block.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#text-domain}
+     */
+    readonly textdomain?: string;
     /**
      * This is the display title for your block, which can be translated
      * with our translation functions.
@@ -119,6 +186,19 @@ export interface Block<T extends Record<string, any> = {}> {
          */
         readonly to?: readonly Transform[] | undefined;
     } | undefined;
+    /**
+     * Array of the names of context values to inherit from an ancestor
+     * provider.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#context}
+     */
+    readonly usesContext?: string[];
+    /**
+     * The current version number of the block, such as 1.0 or 1.0.3.
+     *
+     * @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#version}
+     */
+    readonly version?: string;
     /**
      * Sets attributes on the topmost parent element of the current block.
      */

types/wordpress__blocks/wordpress__blocks-tests.tsx

@@ -369,6 +369,65 @@ blocks.registerBlockType<{ foo: string }>('my/foo', {
     category: 'common',
 });
 
+// Register with block.json metadata
+// https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
+blocks.registerBlockType({
+    apiVersion: 2,
+    name: 'my-plugin/notice',
+    title: 'Notice',
+    category: 'text',
+    parent: ['core/group'],
+    icon: 'star-half',
+    description: 'Shows warning, error or success notices…',
+    keywords: ['alert', 'message'],
+    version: '1.0.3',
+    textdomain: 'my-plugin',
+    attributes: {
+        message: {
+            type: 'string',
+            source: 'html',
+            selector: '.message',
+        },
+    },
+    providesContext: {
+        'my-plugin/message': 'message',
+    },
+    usesContext: ['groupId'],
+    supports: {
+        align: true,
+    },
+    styles: [
+        { name: 'default', label: 'Default', isDefault: true },
+        { name: 'other', label: 'Other' },
+    ],
+    example: {
+        attributes: {
+            message: 'This is a notice!',
+        },
+        innerBlocks: [
+            {
+                name: 'core/paragraph',
+                attributes: {
+                    content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent et eros eu felis.',
+                },
+                innerBlocks: [
+                    {
+                        name: 'core/paragraph',
+                        attributes: {
+                            content:
+                                'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent et eros eu felis.',
+                        },
+                    },
+                ],
+            },
+        ],
+    },
+    editorScript: 'file:./build/index.js',
+    script: 'file:./build/script.js',
+    editorStyle: 'file:./build/index.css',
+    style: 'file:./build/style.css',
+});
+
 // $ExpectType void
 blocks.setDefaultBlockName('my/foo');