@wordpress/create-block 4.0.1-next.d6164808d3.0 → 4.1.0

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-## 4.0.0-next.0 (2022-08-23)
+## 4.0.0 (2022-08-24)
 
 ### Breaking Change
 
@@ -11,7 +11,7 @@
 ### New Feature
 
 -   Add `--no-plugin` flag to allow scaffolding of a block in an existing plugin ([#41642](https://github.com/WordPress/gutenberg/pull/41642))
--   Introduce the `--variant` flag to allow selection of a variant as defined in the template ([#41289](https://github.com/WordPress/gutenberg/pull/41289)).
+-   Introduce the `--variant` flag to allow selection of a variant as defined in the template ([#41289](https://github.com/WordPress/gutenberg/pull/41289), [#43481](https://github.com/WordPress/gutenberg/pull/43481)).
 
 ## 3.6.0 (2022-07-13)
 

package/README.md

@@ -24,6 +24,8 @@ _(requires `node` version `14.0.0` or above, and `npm` version `6.14.4` or above
 
 It creates a WordPress plugin that you need to [install manually](https://wordpress.org/support/article/managing-plugins/#manual-plugin-installation).
 
+[Watch a video introduction to create-block on Learn.wordpress.org](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)
+
 ## Usage
 
 The following command generates a project with PHP, JS, and CSS code for registering a block with a WordPress plugin.
@@ -87,7 +89,6 @@ $ npx @wordpress/create-block --help
 
 5. No plugin mode – it is also possible to scaffold only block files into the current directory.
 
-
 ```bash
 $ npx @wordpress/create-block --no-plugin
 ```
@@ -144,107 +145,7 @@ _Note: You don’t need to install or configure tools like [webpack](https://web
 
 ## External Project Templates
 
-Are you looking for a way to share your project configuration? Creating an external project template hosted on npm or located in a local directory is possible. These npm packages can provide custom `.mustache` files that replace default files included in the tool for the WordPress plugin or/and the block. It's also possible to override default configuration values used during the scaffolding process.
-
-### Project Template Configuration
-
-Providing the main file (`index.js` by default) for the package that returns a configuration object is mandatory. Several options allow customizing the scaffolding process.
-
-#### `pluginTemplatesPath`
-
-This optional field allows overriding file templates related to **the WordPress plugin shell**. The path points to a location with template files ending with the `.mustache` extension (nested folders are also supported). When not set, the tool uses its own set of templates.
-
-_Example:_
-
-```js
-const { join } = require( 'path' );
-
-module.exports = {
-	pluginTemplatesPath: join( __dirname, 'plugin-templates' ),
-};
-```
-
-#### `blockTemplatesPath`
-
-This optional field allows overriding file templates related to **the individual block**. The path points to a location with template files ending with the `.mustache` extension (nested folders are also supported). When not set, the tool uses its own set of templates.
-
-_Example:_
-
-```js
-const { join } = require( 'path' );
-
-module.exports = {
-	blockTemplatesPath: join( __dirname, 'block-templates' ),
-};
-```
-
-#### `assetsPath`
-
-This setting is useful when your template scaffolds a WordPress plugin that uses static assets like images or fonts, which should not be processed. It provides the path pointing to the location where assets are located. They will be copied to the `assets` subfolder in the generated plugin.
-
-_Example:_
-
-```js
-const { join } = require( 'path' );
-
-module.exports = {
-	assetsPath: join( __dirname, 'plugin-assets' ),
-};
-```
-
-#### `defaultValues`
-
-It is possible to override the default template configuration using the `defaultValues` field.
-
-_Example:_
-
-```js
-module.exports = {
-	defaultValues: {
-		slug: 'my-fantastic-block',
-		title: 'My fantastic block',
-		dashicon: 'palmtree',
-		version: '1.2.3',
-	},
-};
-```
-
-The following configurable variables are used with the template files. Template authors can change default values to use when users don't provide their data.
-
-**Project**:
-
--   `wpScripts` (default: `true`) – enables integration with the `@wordpress/scripts` package and adds common scripts to the `package.json`.
--   `wpEnv` (default: `false`) – enables integration with the `@wordpress/env` package and adds the `env` script to the `package.json`.
--   `customScripts` (default: {}) – the list of custom scripts to add to `package.json` . It also allows overriding default scripts.
--   `npmDependencies` (default: `[]`) – the list of remote npm packages to be installed in the project with [`npm install`](https://docs.npmjs.com/cli/v8/commands/npm-install) when `wpScripts` is enabled.
--   `npmDevDependencies` (default: `[]`) – the list of remote npm packages to be installed in the project with [`npm install --save-dev`](https://docs.npmjs.com/cli/v8/commands/npm-install) when `wpScripts` is enabled.
-
-**Plugin header fields** ([learn more](https://developer.wordpress.org/plugins/plugin-basics/header-requirements/)):
-
--   `pluginURI` (no default) – the home page of the plugin.
--   `version` (default: `'0.1.0'`) – the current version number of the plugin.
--   `author` (default: `'The WordPress Contributors'`) – the name of the plugin author(s).
--   `license` (default: `'GPL-2.0-or-later'`) – the short name of the plugin’s license.
--   `licenseURI` (default: `'https://www.gnu.org/licenses/gpl-2.0.html'`) – a link to the full text of the license.
--   `domainPath` (no default) – a custom domain path for the translations ([more info](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#domain-path)).
--   `updateURI:` (no default) – a custom update URI for the plugin ([related dev note](https://make.wordpress.org/core/2021/06/29/introducing-update-uri-plugin-header-in-wordpress-5-8/)).
-
-**Block metadata** ([learn more](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)):
-
--   `folderName` (default: `.`) – the location for the `block.json` file and other optional block files generated from block templates included in the folder set with the `blockTemplatesPath` setting.
--   `$schema` (default: `https://schemas.wp.org/trunk/block.json`) – the schema URL used for block validation.
--   `apiVersion` (default: `2`) – the block API version ([related dev note](https://make.wordpress.org/core/2020/11/18/block-api-version-2/)).
--   `slug` (no default) – the block slug used for identification in the block name.
--   `namespace` (default: `'create-block'`) – the internal namespace for the block name.
--   `title` (no default) – a display title for your block.
--   `description` (no default) – a short description for your block.
--   `dashicon` (no default) – an icon property thats makes it easier to identify a block ([available values](https://developer.wordpress.org/resource/dashicons/)).
--   `category` (default: `'widgets'`) – blocks are grouped into categories to help users browse and discover them. The categories provided by core are `text`, `media`, `design`, `widgets`, `theme`, and `embed`.
--   `attributes` (no default) – block attributes ([more details](https://developer.wordpress.org/block-editor/developers/block-api/block-attributes/)).
--   `supports` (no default) – optional block extended support features ([more details](https://developer.wordpress.org/block-editor/developers/block-api/block-supports/).
--   `editorScript` (default: `'file:./index.js'`) – an editor script definition.
--   `editorStyle` (default: `'file:./index.css'`) – an editor style definition.
--   `style` (default: `'file:./style-index.css'`) – a frontend and editor style definition.
+[Click here](https://github.com/WordPress/gutenberg/tree/HEAD/packages/create-block/docs/external-template.md) for information on External Project Templates
 
 ## Contributing to this package
 

package/lib/index.js

@@ -77,10 +77,22 @@ program
 			await checkSystemRequirements( engines );
 			try {
 				const pluginTemplate = await getPluginTemplate( templateName );
-				const defaultValues = getDefaultValues(
-					pluginTemplate,
-					variant
+				const availableVariants = Object.keys(
+					pluginTemplate.variants
 				);
+				if ( variant && ! availableVariants.includes( variant ) ) {
+					if ( ! availableVariants.length ) {
+						throw new CLIError(
+							`"${ variant }" variant was selected. This template does not have any variants!`
+						);
+					}
+					throw new CLIError(
+						`"${ variant }" is not a valid variant for this template. Available variants are: ${ availableVariants.join(
+							', '
+						) }.`
+					);
+				}
+
 				const optionsValues = Object.fromEntries(
 					Object.entries( {
 						plugin,
@@ -90,11 +102,14 @@ program
 						title,
 						wpScripts,
 						wpEnv,
-						variant,
 					} ).filter( ( [ , value ] ) => value !== undefined )
 				);
 
 				if ( slug ) {
+					const defaultValues = getDefaultValues(
+						pluginTemplate,
+						variant
+					);
 					const answers = {
 						...defaultValues,
 						slug,
@@ -111,19 +126,24 @@ program
 							: "Let's add a new block to your existing WordPress plugin:"
 					);
 
-					const filterOptionsProvided = ( { name } ) =>
-						! Object.keys( optionsValues ).includes( name );
+					if ( ! variant && availableVariants.length > 1 ) {
+						const result = await inquirer.prompt( {
+							type: 'list',
+							name: 'variant',
+							message:
+								'The template variant to use for this block:',
+							choices: availableVariants,
+						} );
+						variant = result.variant;
+					}
 
-					// Get the variant prompt first. This will help get the default values
-					const variantPrompt =
-						Object.keys( pluginTemplate.variants )?.length > 1
-							? getPrompts( pluginTemplate, [ 'variant' ] )
-							: false;
-
-					const variantSelection = variantPrompt
-						? await inquirer.prompt( variantPrompt )
-						: false;
+					const defaultValues = getDefaultValues(
+						pluginTemplate,
+						variant
+					);
 
+					const filterOptionsProvided = ( { name } ) =>
+						! Object.keys( optionsValues ).includes( name );
 					const blockPrompts = getPrompts(
 						pluginTemplate,
 						[
@@ -134,9 +154,8 @@ program
 							'dashicon',
 							'category',
 						],
-						variantSelection.variant
+						variant
 					).filter( filterOptionsProvided );
-
 					const blockAnswers = await inquirer.prompt( blockPrompts );
 
 					const pluginAnswers = plugin
@@ -163,7 +182,8 @@ program
 											'licenseURI',
 											'domainPath',
 											'updateURI',
-										]
+										],
+										variant
 									).filter( filterOptionsProvided );
 									const result = await inquirer.prompt(
 										pluginPrompts
@@ -175,8 +195,8 @@ program
 					await scaffold( pluginTemplate, {
 						...defaultValues,
 						...optionsValues,
+						variant,
 						...blockAnswers,
-						...variantSelection,
 						...pluginAnswers,
 					} );
 				}

package/lib/prompts.js

@@ -134,16 +134,8 @@ const updateURI = {
 	message: 'A custom update URI for the plugin (optional):',
 };
 
-const variant = {
-	type: 'list',
-	name: 'variant',
-	message: 'The template variant to use for this block:',
-	choices: [],
-};
-
 module.exports = {
 	slug,
-	variant,
 	namespace,
 	title,
 	description,

package/lib/scaffold.js

@@ -12,10 +12,9 @@ const initWPScripts = require( './init-wp-scripts' );
 const initWPEnv = require( './init-wp-env' );
 const { code, info, success, error } = require( './log' );
 const { writeOutputAsset, writeOutputTemplate } = require( './output' );
-const { getTemplateVariantVars } = require( './templates' );
 
 module.exports = async (
-	{ blockOutputTemplates, pluginOutputTemplates, outputAssets, variants },
+	{ blockOutputTemplates, pluginOutputTemplates, outputAssets },
 	{
 		$schema,
 		apiVersion,
@@ -44,7 +43,7 @@ module.exports = async (
 		editorScript,
 		editorStyle,
 		style,
-		variant,
+		variantVars,
 	}
 ) => {
 	slug = slug.toLowerCase();
@@ -100,8 +99,7 @@ module.exports = async (
 		editorScript,
 		editorStyle,
 		style,
-		...getTemplateVariantVars( variants, variant ),
-		...variants[ variant ],
+		...variantVars,
 	};
 
 	if ( plugin ) {
@@ -146,7 +144,7 @@ module.exports = async (
 	success(
 		plugin
 			? `Done: WordPress plugin ${ title } bootstrapped in the ${ slug } directory.`
-			: `Done: Block "${ title }" bootstrapped in the ${ slug }directory.`
+			: `Done: Block "${ title }" bootstrapped in the ${ slug } directory.`
 	);
 
 	if ( plugin && wpScripts ) {

package/lib/templates/block/index.js.mustache

@@ -34,6 +34,7 @@ registerBlockType( metadata.name, {
 	 */
 	edit: Edit,
 	{{#isStaticVariant}}
+
 	/**
 	 * @see ./save.js
 	 */

package/lib/templates/es5/$slug.php.mustache

@@ -68,32 +68,24 @@ function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
 		array(),
 		filemtime( "$dir/$style_css" )
 	);
-	{{^isDynamicVariant}}
+
 	register_block_type(
 		'{{namespace}}/{{slug}}',
 		array(
 			'editor_script' => '{{namespace}}-{{slug}}-block-editor',
 			'editor_style'  => '{{namespace}}-{{slug}}-block-editor',
 			'style'         => '{{namespace}}-{{slug}}-block',
-		)
-	);
-	{{/isDynamicVariant}}
-	{{#isDynamicVariant}}
-	register_block_type(
-		'{{namespace}}/{{slug}}',
-		array(
-			'editor_script'   => '{{namespace}}-{{slug}}-block-editor',
-			'editor_style'    => '{{namespace}}-{{slug}}-block-editor',
-			'style'           => '{{namespace}}-{{slug}}-block',
+			{{#isDynamicVariant}}
 			'render_callback' => '{{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback',
+			{{/isDynamicVariant}}
 		)
 	);
-	{{/isDynamicVariant}}
 }
 add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );
 {{#isDynamicVariant}}
+
 /**
- * Render callback function
+ * Render callback function.
  *
  * @param array    $attributes The block attributes.
  * @param string   $content    The block content.
@@ -101,7 +93,7 @@ add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );
  *
  * @return string The rendered output.
  */
-function {{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback( $atts, $content, $block) {
+function {{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback( $attributes, $content, $block ) {
 	ob_start();
 	require plugin_dir_path( __FILE__ ) . '/template.php';
 	return ob_get_clean();

package/lib/templates/es5/index.js.mustache

@@ -94,7 +94,9 @@
 				useBlockProps(),
 				__( '{{title}} – hello from the editor!', '{{textdomain}}' )
 			);
-		}{{#isStaticVariant}},
+		},
+		{{#isStaticVariant}}
+
 		/**
 		 * The save function defines the way in which the different attributes should be combined
 		 * into the final markup, which is then serialized by the block editor into `post_content`.

package/lib/templates/plugin/$slug.php.mustache

@@ -37,25 +37,24 @@
  *
  * @see https://developer.wordpress.org/reference/functions/register_block_type/
  */
-{{#isStaticVariant}}
 function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
+	{{#isStaticVariant}}
 	register_block_type( __DIR__ . '/build' );
-}
-add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );
-{{/isStaticVariant}}
-{{#isDynamicVariant}}
-function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
+	{{/isStaticVariant}}
+	{{#isDynamicVariant}}
 	register_block_type(
 		__DIR__ . '/build',
 		array(
 			'render_callback' => '{{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback',
 		)
 	);
+	{{/isDynamicVariant}}
 }
 add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );
+{{#isDynamicVariant}}
 
 /**
- * Render callback function
+ * Render callback function.
  *
  * @param array    $attributes The block attributes.
  * @param string   $content    The block content.
@@ -63,7 +62,7 @@ add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );
  *
  * @return string The rendered output.
  */
-function {{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback( $atts, $content, $block) {
+function {{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback( $attributes, $content, $block ) {
 	ob_start();
 	require plugin_dir_path( __FILE__ ) . 'build/template.php';
 	return ob_get_clean();

package/lib/templates.js

@@ -111,9 +111,9 @@ const externalTemplateExists = async ( templateName ) => {
 const configToTemplate = async ( {
 	pluginTemplatesPath,
 	blockTemplatesPath,
-	defaultValues = {},
 	assetsPath,
-	variants,
+	defaultValues = {},
+	variants = {},
 	...deprecated
 } ) => {
 	if ( defaultValues === null || typeof defaultValues !== 'object' ) {
@@ -140,9 +140,9 @@ const configToTemplate = async ( {
 		blockOutputTemplates: blockTemplatesPath
 			? await getOutputTemplates( blockTemplatesPath )
 			: {},
-		defaultValues,
-		outputAssets: assetsPath ? await getOutputAssets( assetsPath ) : {},
 		pluginOutputTemplates: await getOutputTemplates( pluginTemplatesPath ),
+		outputAssets: assetsPath ? await getOutputAssets( assetsPath ) : {},
+		defaultValues,
 		variants,
 	};
 };
@@ -231,25 +231,14 @@ const getDefaultValues = ( pluginTemplate, variant ) => {
 		editorStyle: 'file:./index.css',
 		style: 'file:./style-index.css',
 		...pluginTemplate.defaultValues,
-		...pluginTemplate.variants[ variant ],
+		...pluginTemplate.variants?.[ variant ],
+		variantVars: getVariantVars( pluginTemplate.variants, variant ),
 	};
 };
 
 const getPrompts = ( pluginTemplate, keys, variant ) => {
-	const defaultValues = getDefaultValues( pluginTemplate );
-	const variantData = pluginTemplate.variants[ variant ] ?? false;
+	const defaultValues = getDefaultValues( pluginTemplate, variant );
 	return keys.map( ( promptName ) => {
-		if ( promptName === 'variant' ) {
-			prompts[ promptName ].choices = Object.keys(
-				pluginTemplate.variants
-			);
-		}
-		if ( variantData && variantData[ promptName ] ) {
-			return {
-				...prompts[ promptName ],
-				default: variantData[ promptName ],
-			};
-		}
 		return {
 			...prompts[ promptName ],
 			default: defaultValues[ promptName ],
@@ -257,28 +246,21 @@ const getPrompts = ( pluginTemplate, keys, variant ) => {
 	} );
 };
 
-const getTemplateVariantVars = ( variants, variant ) => {
+const getVariantVars = ( variants, variant ) => {
 	const variantVars = {};
-	if ( variants ) {
-		const variantNames = Object.keys( variants );
-		const chosenVariant = variant ?? variantNames[ 0 ]; // If no variant is passed, use the first in the array as the default
+	const variantNames = Object.keys( variants );
+	if ( variantNames.length === 0 ) {
+		return variantVars;
+	}
 
-		if ( variantNames.includes( chosenVariant ) ) {
-			for ( const variantName of variantNames ) {
-				const key =
-					variantName.charAt( 0 ).toUpperCase() +
-					variantName.slice( 1 );
-				variantVars[ `is${ key }Variant` ] =
-					chosenVariant === variantName ?? false;
-			}
-		} else {
-			throw new CLIError(
-				`"${ chosenVariant }" is not a valid variant for this template. Available variants are: ${ variantNames.join(
-					', '
-				) }`
-			);
-		}
+	const currentVariant = variant ?? variantNames[ 0 ];
+	for ( const variantName of variantNames ) {
+		const key =
+			variantName.charAt( 0 ).toUpperCase() + variantName.slice( 1 );
+		variantVars[ `is${ key }Variant` ] =
+			currentVariant === variantName ?? false;
 	}
+
 	return variantVars;
 };
 
@@ -286,5 +268,4 @@ module.exports = {
 	getPluginTemplate,
 	getDefaultValues,
 	getPrompts,
-	getTemplateVariantVars,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/create-block",
-	"version": "4.0.1-next.d6164808d3.0",
+	"version": "4.1.0",
 	"description": "Generates PHP, JS and CSS code for registering a block for a WordPress plugin.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -31,7 +31,7 @@
 		"wp-create-block": "./index.js"
 	},
 	"dependencies": {
-		"@wordpress/lazy-import": "^1.4.3-next.d6164808d3.0",
+		"@wordpress/lazy-import": "^1.4.2",
 		"chalk": "^4.0.0",
 		"change-case": "^4.1.2",
 		"check-node-version": "^4.1.0",
@@ -48,5 +48,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "ba8a396d2f418e53a6c4c50575582f3f3eb11ff7"
+	"gitHead": "0d732d4b184adcb28cc83087603e81b764390d4b"
 }