Feature/add block style modifier library

docs/.vitepress/config.mts

@@ -20,6 +20,35 @@ export default defineConfig({
           { text: 'Migrating from Theme Core', link: '/migrating-from-theme-core' }
         ]
       },
+      {
+        text: 'Framework',
+        items: [
+          {
+            text: 'PHP Libraries',
+            link: '/php-libraries',
+            items: [
+              {
+                text: 'Custom Post Types',
+                link: '/php-libraries/custom-post-types'
+              },
+              {
+                text: 'Post Fields',
+                link: '/php-libraries/post-fields'
+              }
+            ]
+          },
+          {
+            text: 'JavaScript Libraries',
+            link: '/js-libraries',
+            items: [
+              {
+                text: 'Block Style Modifier',
+                link: '/js-libraries/block-style-modifier'
+              },
+            ]
+          }
+        ]
+      },
       {
         text: 'Commands',
         items: [

docs/js-libraries.md

@@ -0,0 +1,2 @@
+# JavaScript Libraries
+This project comes with a series of JavaScript libraries that can be used within a theme.

docs/js-libraries/block-style-modifier.md

@@ -0,0 +1,34 @@
+---
+outline: deep
+---
+
+# Block Style Modifier
+
+## Introduction
+This library will allow block styles to be added and removed without the dependency, sequencing and context complications that must be accounted for when using core WordPress functionality.
+
+This will support the style management of both core and custom blocks.
+
+## The class
+You will need to instantiate the Block_Style_Modifier class.
+
+```js
+const blockStyleModifier = new Block_Style_Modifier();
+```
+
+## Removal
+To remove a block style you can use the removeStyle function.
+
+```js
+blockStyleModifier.removeStyle( 'core/button', 'outline' );
+```
+
+## Addition
+To add a block style you can use the addStyle function.
+
+```js
+blockStyleModifier.addStyle( 'core/button', 'arrow', 'Arrow' );
+```
+
+## File architecture
+During a theme installation, a file will be created at the following path, relative to the theme root: /js/admin/block-styles.js. Functionality associated with enqueueing this file will also be installed. Implementation of the Block_Style_Modifier class should be added to this file.

docs/php-libraries.md

@@ -0,0 +1,2 @@
+# PHP Libraries
+This project comes with a series of extendable PHP classes and functionality that can be used within a theme.

docs/php-libraries/custom-post-types.md

@@ -0,0 +1,18 @@
+---
+outline: deep
+---
+
+# Custom Post Types
+
+## Base class extension
+The abstract class Creode_Theme\Base_Post_Type can be extended within your theme to declare a custom post type.
+
+The abstract class uses a singleton design pattern therefore cannot be publicly instantiated. each extension must be initialized by calling the it's static init function.
+
+## File architecture
+During a theme installation, a folder will be created at the following path, relative to the theme root: /includes/post-types. Extension class files should be created within this folder. The folder also contains a file called all.php. This file should used to require extension class files and initialize them.
+
+```php
+require_once __DIR__ . 'class-my-example-post-type.php';
+My_Example_Post_Type::init();
+```

docs/php-libraries/post-fields.md

@@ -0,0 +1,93 @@
+---
+outline: deep
+---
+
+# Post Fields
+
+## Base class extension
+The abstract class Creode_Theme\Base_Post_Fields can be extended within your theme to declare a field group against a single post type or multiple post types.
+
+The abstract class uses a singleton design pattern therefore cannot be publicly instantiated. each extension must be initialized by calling the it's static init function.
+
+The base class uses ACF Pro to manage these fields therefore this must be installed.
+
+Extension classes must define information about the field group and an ACF fields array.
+
+The base class works by assigning the field group to post types which support a particular custom feature (support). This can be defined by extending the support function and returning the applicable support feature string.
+
+```php
+/**
+ * Class to register post logo fields.
+ */
+class Logo_Post_Fields extends Base_Post_Fields {
+
+	/**
+	 * {@inheritdoc}
+	 */
+	protected function group_name(): string {
+		return 'logo';
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	protected function group_title(): string {
+		return 'Logo';
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	protected function fields(): array {
+		return array(
+			array(
+				'key'           => 'field_logo',
+				'name'          => 'logo',
+				'label'         => 'Logo',
+				'type'          => 'image',
+				'return_format' => 'ID',
+			),
+		);
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	protected function support(): string {
+		return 'logo';
+	}
+}
+```
+
+## Custom supports
+
+The example above requires that applicable post types support the "logo" custom feature (support). This means that custom post types must include this within their supports array:
+
+```php
+/**
+ * {@inheritdoc}
+ */
+protected function args(): array {
+  return array(
+    'supports' => array(
+      'title',
+      'editor',
+      'thumbnail',
+      'excerpt',
+      'logo',
+    ),
+    'show_in_rest' => true,
+    'has_archive'  => true,
+  );
+}
+```
+
+Pre-existing post types can have additional supports added by using the add_post_type_support function: https://developer.wordpress.org/reference/functions/add_post_type_support/
+
+## File architecture
+During a theme installation, a folder will be created at the following path, relative to the theme root: /includes/post-fields. Extension class files should be created within this folder. The folder also contains a file called all.php. This file should used to require extension class files and initialize them.
+
+```php
+require_once __DIR__ . 'class-logo-post-fields.php';
+Logo_Post_Fields::init();
+```

includes/register-js-libraries.php

@@ -0,0 +1,17 @@
+<?php
+/**
+ * File register JavaScript libraries.
+ *
+ * @package Creode Theme
+ */
+
+/**
+ * Function to register JavaScript libraries.
+ */
+function register_js_libraries() {
+	$base_url = WPMU_PLUGIN_URL . '/wordpress-theme/js-libraries/';
+	wp_register_script( 'block_style_modifier', $base_url . 'block-style-modifier.js', array(), '1.0.0', true );
+}
+
+add_action( 'wp_enqueue_scripts', 'register_js_libraries' );
+add_action( 'admin_enqueue_scripts', 'register_js_libraries' );

js-libraries/block-style-modifier.js

@@ -0,0 +1,90 @@
+/**
+ * Class to handle the addition and removal of block styles.
+ * Functions "addStyle" and "removeStyle" can be called an any time because this class handles the awaiting of dependencies.
+ */
+class Block_Style_Modifier {
+
+	/**
+	 * Add a style to an existing block.
+	 *
+	 * @param {string} blockName The full name of the block to add a style to.
+	 * @param {string} styleName The name of the style to add. Should be lowercase, hypen separated and contain no spaces.
+	 * @param {string} styleLabel Human readable text to represent the style.
+	 */
+	async addStyle(blockName, styleName, styleLabel) {
+		await this.awaitDependencies();
+		wp.blocks.registerBlockStyle(
+			blockName,
+			{
+				name: styleName,
+				label: styleLabel,
+			}
+		);
+	}
+
+	/**
+	 * Remove a style from an existing block.
+	 *
+	 * @param {string} blockName The full name of the block to remove the style from.
+	 * @param {string} styleName The name of the style to remove.
+	 */
+	async removeStyle(blockName, styleName) {
+		await this.awaitDependencies();
+		await this.awaitStyleAvailability(blockName, styleName);
+		wp.blocks.unregisterBlockStyle(blockName, styleName);
+	}
+
+	/**
+	 * Wait until WordPress Blocks API is available.
+	 */
+	async awaitDependencies() {
+		await new Promise(
+			(resolve) => {
+				const interval = setInterval(
+					() => {
+						if (typeof wp == 'undefined') {
+							return;
+						}
+						if (typeof wp.blocks == 'undefined') {
+							return;
+						}
+
+						clearInterval(interval);
+						resolve();
+					},
+					10
+				);
+			}
+		);
+	}
+
+	/**
+	 * Waits for a style to become availible for a particular block.
+	 *
+	 * @param {string} blockName The name of the block.
+	 * @param {string} styleName The name of the style.
+	 */
+	async awaitStyleAvailability(blockName, styleName) {
+		await new Promise(
+			(resolve) => {
+				const interval = setInterval(
+					() => {
+						const block = wp.blocks.getBlockType(blockName);
+
+						if (typeof block == 'undefined') {
+							return;
+						}
+
+						if (!block.styles.filter((style) => { return style.name == styleName; }).length) {
+							return;
+						}
+
+						clearInterval(interval);
+						resolve();
+					},
+					10
+				);
+			}
+		);
+	}
+}

plugin.php

@@ -27,6 +27,7 @@
 require_once __DIR__ . '/includes/class-command-base.php';
 require_once __DIR__ . '/includes/commands/all.php';
 require_once __DIR__ . '/includes/class-asset-enqueue.php';
+require_once __DIR__ . '/includes/register-js-libraries.php';
 
 // Register commands.
 Install_Theme_Command::register();

theme-template/includes/register-scripts.php

@@ -20,3 +20,16 @@ function () {
 		wp_enqueue_script( 'example_script' );
 	}
 );
+
+/**
+ * Enqueues admin scripts.
+ */
+add_action(
+	'admin_enqueue_scripts',
+	function () {
+		$asset_enqueue = Asset_Enqueue::get_instance();
+
+		$asset_enqueue->register_vite_script( 'block_styles', 'js/admin/block-styles.js', array( 'block_style_modifier' ) );
+		wp_enqueue_script( 'block_styles' );
+	}
+);

theme-template/js/admin/block-styles.js

@@ -0,0 +1,8 @@
+/**
+ * JavaScript to update core block styles for necessary theming.
+*/
+
+// Example usage of Block_Style_Modifier:
+// const blockStyleModifier = new Block_Style_Modifier();
+// blockStyleModifier.removeStyle( 'core/button', 'outline' );
+// blockStyleModifier.addStyle( 'core/button', 'arrow', 'Arrow' );

theme-template/vite.config.js

@@ -20,6 +20,7 @@ export default defineConfig(
 				rollupOptions: {
 					// overwrite default .html entry
 					input: {
+						blockStyles: resolve(__dirname, 'js/admin/block-styles.js'),
 						main: resolve(__dirname, 'vite-entry-points/main.js'),
 						admin: resolve(__dirname, 'vite-entry-points/admin.js'),
 					}