Merge pull request #25 from WebDevStudios/feature/WDSBT-20-custom-blocks

Feature/WDSBT-20 Custom block build process

.eslintignore

@@ -1,3 +1,4 @@
+blocks
 build
 node_modules
 vendor

.gitignore

@@ -23,6 +23,7 @@ vendor/
 
 # theme
 build/
+blocks/
 
 #tests
 pa11y-ci-report/

.markdownlintignore

@@ -1,3 +1,4 @@
+blocks
 build
 node_modules
 vendor

.prettierignore

@@ -1,5 +1,7 @@
+blocks/
 build/
 node_modules/
 vendor/
 style.css
 README.md
+acf-json/

.stylelintignore

@@ -1,3 +1,4 @@
+blocks/
 build/
 vendor/
 node_modules/

README.md

@@ -17,6 +17,7 @@
 - [Getting Started](#getting-started)
 - [Development](#development)
     - [NPM Scripts](#npm-scripts)
+- [Creating Custom Blocks](#creating-blocks)
 - [Customizations](#customizations)
         - [Implementation](#implementation)
     - [Mixins](#mixins)
@@ -205,6 +206,7 @@ npm run setup
 |-------|---------|-------------|
 | 🌐 | `npm run a11y` | Run accessibility tests using Pa11y-CI. |
 | 🛠️ | `npm run build` | Build the theme using `wp-scripts`. |
+| 🔨 | `npm run create-block` | Create a custom block with Webpack and @wordpress/create-block. |
 | 📝 | `npm run format` | Format files using `wp-scripts` and `composer`. |
 | 🔍 | `npm run lint` | Run all linting scripts. |
 | 🎨 | `npm run lint:css` | Lint CSS files using `wp-scripts`. |
@@ -218,6 +220,30 @@ npm run setup
 | ▶️ | `npm run start` | Start the development server using `wp-scripts`. |
 
 
+[🔝 Back to Top](#wds-bt)
+***
+
+## Creating Blocks
+
+1. Run the Block Creation Script
+   Navigate to your project root in the terminal and run the following command to create a new block:
+
+```bash
+npm run create-block
+```
+
+Follow the prompts to configure your new block. The script will scaffold a new block structure inside assets/blocks/.
+
+2. Build your block
+   After editing and configuring your block, build your project to compile assets using webpack:
+
+```bash
+npm run build
+```
+This will process JavaScript, SCSS, optimize images, and generate necessary files in the build/ directory and custom blocks will have files generated in the blocks/ directory.
+
+
+
 [🔝 Back to Top](#wds-bt)
 ***
 
@@ -245,13 +271,13 @@ npm run setup
 </details>
 
 <details closed>
-<summary><b>Overriding/Customizing Core Block Styles</b></summary>
+<summary><b>Overriding/Customizing Block Styles</b></summary>
 
-1. Navigate to the `assets/scss/blocks/core` directory within your theme.
+1. Navigate to the `assets/scss/blocks/` directory within your theme. If overriding a core block style, use the `core` folder, if overriding a block from a plugin use the `custom` folder.
 
-2. Create an SCSS file with the exact filename as the block name you want to customize. This file will house your custom styles for that specific core block.
+2. Create an SCSS file with the exact filename as the block name you want to customize. This file will house your custom styles for that specific block.
 
-3. Files within the `assets/scss/blocks/core` directory are automatically enqueued, simplifying the integration of your custom styles into the WordPress block editor. Do not import these files into the main `index.scss`
+3. Files within the `assets/scss/blocks/core/` directory are automatically enqueued, simplifying the integration of your custom styles into the WordPress block editor. Do not import these files into the main `index.scss`
 
 4. After adding your custom SCSS file, run the following command to compile and apply your changes:
 

assets/scss/editor.scss

@@ -0,0 +1 @@
+/* -- Editor Stykes -- */

babel.config.json

@@ -0,0 +1,3 @@
+{
+  "presets": ["@babel/preset-env", "@babel/preset-react"]
+}

composer.json

@@ -25,14 +25,15 @@
 		"composer/installers": "^2.2.0"
 	},
 	"require-dev": {
+		"php": ">=8.0",
 		"dealerdirect/phpcodesniffer-composer-installer": "^1.0.0",
 		"phpcompatibility/phpcompatibility-wp": "^2.1.4",
 		"squizlabs/php_codesniffer": "^3.10.1",
 		"wp-cli/wp-cli-bundle": "^2.10.0",
 		"wp-coding-standards/wpcs": "^3.1.0"
 	},
 	"scripts": {
-		"fix": "./vendor/bin/phpcbf --report=summary,source",
-		"lint": "./vendor/bin/phpcs --report=summary,source"
+		"phpcs": "./vendor/bin/phpcs --report=full,source",
+		"phpcs-fix": "./vendor/bin/phpcbf --report=summary,source"
 	}
 }

inc/block-template/README.md

@@ -0,0 +1,26 @@
+# WDS Block Template
+
+This template is configured to generate a block that is ready for block registration using the [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) tool.
+
+## Usage
+
+Run the following in the terminal of your choice:
+
+`npx @wordpress/create-block --template ../../inc/block-template  --no-plugin`
+
+
+## Structure
+
+Once the command has completed, the following structure will be created:
+
+``` text
+📁src
+└── 📁blocks
+    └── 📁{example-block}
+        └── block.json
+        └── edit.js
+        └── editor.scss
+        └── index.js
+        └── render.php
+        └── style.scss
+```

inc/block-template/block/edit.js.mustache

@@ -0,0 +1,22 @@
+/**
+ * WordPress Dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * Internal Dependencies
+ */
+import './editor.scss';
+
+/**
+ * The edit function describes the structure of your block in the context of the
+ * editor. This represents what the editor will render when the block is used.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#edit
+ */
+export default function Edit() {
+	return (
+		<p {...useBlockProps()}>{__('{{title}} – hello from the editor!', '{{textdomain}}')}</p>
+	);
+}

inc/block-template/block/editor.scss.mustache

@@ -0,0 +1,9 @@
+/**
+ * The following styles get applied inside the editor only.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-{{namespace}}-{{slug}} {
+	border: 1px dotted var(--wp--preset--color--grey-400);
+}

inc/block-template/block/index.js.mustache

@@ -0,0 +1,33 @@
+/**
+ * Registers a new block provided a unique name and an object defining its behavior.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
+ */
+import { registerBlockType } from '@wordpress/blocks';
+
+/**
+ * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
+ * All files containing `style` keyword are bundled together. The code used
+ * gets applied both to the front of your site and to the editor.
+ *
+ * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
+ */
+import './style.scss';
+
+/**
+ * Internal dependencies
+ */
+import Edit from './edit';
+import metadata from './block.json';
+
+/**
+ * Every block starts by registering a new block type definition.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
+ */
+registerBlockType(metadata.name, {
+	/**
+	 * @see ./edit.js
+	 */
+	edit: Edit,
+});

inc/block-template/block/render.php.mustache

@@ -0,0 +1,35 @@
+<?php
+/**
+ * PHP file to use when rendering the block type on the server to show on the front end.
+ *
+ * The following variables are exposed to the file:
+ *     $attributes (array): The block attributes.
+ *     $content (string): The block default content.
+ *     $block (WP_Block): The block instance.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
+ */
+
+{{#isInteractiveVariant}}
+// Define some global state
+wp_interactivity_state(
+	'{{slug}}',
+	array()
+);
+
+// Define some context.
+$context = array();
+?>
+<p <?php echo wp_kses_data( get_block_wrapper_attributes() ); ?>
+	data-wp-interactive="{{slug}}"
+	<?php echo wp_interactivity_data_wp_context( $context ); ?>
+>
+	<?php esc_html_e( '{{title}} – hello from an interactive block!', '{{textdomain}}' ); ?>
+</p>
+{{/isInteractiveVariant}}
+{{#isDynamicVariant}}
+?>
+<p <?php echo wp_kses_data( get_block_wrapper_attributes() ); ?>>
+	<?php esc_html_e( '{{title}} – hello from a dynamic block!', '{{textdomain}}' ); ?>
+</p>
+{{/isDynamicVariant}}

inc/block-template/block/style.scss.mustache

@@ -0,0 +1,10 @@
+/**
+ * The following styles get applied both on the front of your site
+ * and in the editor.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-{{namespace}}-{{slug}} {
+	border: 1px dotted var(--wp--preset--color--grey-400);
+}

inc/block-template/block/view.js.mustache

@@ -0,0 +1,12 @@
+{{#isInteractiveVariant}}
+/**
+ * WordPress dependencies
+ */
+import { store } from '@wordpress/interactivity';
+
+store( '{{slug}}', {
+	state: {},
+	actions: {},
+	callbacks: {},
+} );
+{{/isInteractiveVariant}}

inc/block-template/index.js

@@ -0,0 +1,43 @@
+/**
+ * Dependencies
+ */
+const { join } = require('path');
+
+module.exports = {
+	defaultValues: {
+		transformer: (view) => {
+			const {
+				variantVars: { isInteractiveVariant },
+			} = view;
+			return {
+				...view,
+				requiresAtLeast: isInteractiveVariant ? '6.5' : '6.1',
+			};
+		},
+		author: 'WebDevStudios',
+		category: 'wds-blocks',
+		dashicon: 'pets',
+		description: 'A custom block created by the create-block for the theme',
+		namespace: 'wdsbt',
+		render: 'file:./render.php',
+		version: '1.0.0',
+		customPackageJSON: {
+			prettier: '@wordpress/prettier-config',
+		},
+	},
+	variants: {
+		dynamic: {},
+		interactive: {
+			viewScriptModule: 'file:./view.js',
+			customScripts: {
+				build: 'wp-scripts build --experimental-modules',
+				start: 'wp-scripts start --experimental-modules',
+			},
+			supports: {
+				interactive: true,
+			},
+		},
+	},
+	pluginTemplatesPath: join(__dirname, 'plugin'),
+	blockTemplatesPath: join(__dirname, 'block'),
+};

inc/block-template/plugin/$slug.php.mustache

@@ -0,0 +1,49 @@
+<?php
+/**
+ * Plugin Name:       {{title}}
+{{#pluginURI}}
+ * Plugin URI:        {{{pluginURI}}}
+{{/pluginURI}}
+{{#description}}
+ * Description:       {{description}}
+{{/description}}
+ * Requires at least: {{requiresAtLeast}}
+ * Requires PHP:      7.0
+ * Version:           {{version}}
+{{#author}}
+ * Author:            {{author}}
+{{/author}}
+{{#license}}
+ * License:           {{license}}
+{{/license}}
+{{#licenseURI}}
+ * License URI:       {{{licenseURI}}}
+{{/licenseURI}}
+ * Text Domain:       {{textdomain}}
+{{#domainPath}}
+ * Domain Path:       {{{domainPath}}}
+{{/domainPath}}
+{{#updateURI}}
+ * Update URI:        {{{updateURI}}}
+{{/updateURI}}
+ *
+ * @package {{slugPascalCase}}
+ */
+
+namespace {{slugPascalCase}};
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit; // Exit if accessed directly.
+}
+
+/**
+ * Registers the block using the metadata loaded from the `block.json` file.
+ * Behind the scenes, it registers also all assets so they can be enqueued
+ * through the block editor in the corresponding context.
+ *
+ * @see https://developer.wordpress.org/reference/functions/register_block_type/
+ */
+function {{slugSnakeCase}}_block_init() {
+	register_block_type_from_metadata( __DIR__ . '/build' );
+}
+add_action( 'init', __NAMESPACE__ . '{{slugSnakeCase}}_block_init' );