Merge pull request #82 from alleyinteractive/feature/wp-scripts

Add support for @wordpress/scripts, block.json and create block

.editorconfig

@@ -8,7 +8,7 @@ insert_final_newline = true
 indent_style = tab
 indent_size = 4
 
-[*.{js,jsx,scss,css,json,yaml,yml,feature,xml}]
+[*.{ts,tsx,js,jsx,scss,css,json,yaml,yml,feature,xml}]
 indent_style = space
 indent_size = 2
 

.eslintrc.json

@@ -5,14 +5,15 @@
     "jest": true,
     "node": true
   },
-  "extends": ["airbnb", "airbnb/hooks"],
-  "parser": "@babel/eslint-parser",
+  "extends": ["airbnb", "airbnb-typescript", "airbnb/hooks"],
+  "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "ecmaFeatures": {
       "globalReturn": true,
       "impliedStrict": true,
       "jsx": true
     },
+    "project": "./tsconfig.json",
     "sourceType": "module"
   },
   "rules": {
@@ -26,7 +27,10 @@
         "message": "Ternaries must be used instead of || in JSX expressions to avoid the potential for accidental output. Use, for example, {thing1 ? thing1 : thing2}.",
         "selector": ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='||']"
       }
-    ]
+    ],
+    "react/jsx-props-no-spreading": "off",
+    "react/react-in-jsx-scope": "off",
+    "react/require-default-props": "off"
   },
   "settings": {
     "import/resolver": "webpack"

.phpcs.xml

@@ -46,6 +46,9 @@
   <!-- Disable commenting rules for example code included in the plugin. -->
   <rule ref="Squiz.PHP.CommentedOutCode.Found">
     <exclude-pattern>src/assets.php</exclude-pattern>
+    <exclude-pattern>blocks</exclude-pattern>
+    <exclude-pattern>build</exclude-pattern>
+    <exclude-pattern>entries</exclude-pattern>
   </rule>
 
   <rule ref="Squiz.Commenting.InlineComment">

.stylelintrc.json

@@ -1,24 +1,3 @@
 {
-  "extends": "stylelint-config-sass-guidelines",
-  "rules": {
-    "max-nesting-depth": [
-      3,
-      {
-        "ignoreAtRules": [
-          "each",
-          "media",
-          "supports",
-          "include"
-        ]
-      }
-    ],
-    "selector-class-pattern": [
-      "^[a-z0-9\\-_]+$",
-      {
-        "message":
-        "Selector should be written in lowercase with hyphens and/or underscores (selector-class-pattern)"
-      }
-    ],
-    "selector-no-qualifying-type": null
-  }
-}
+	"extends": "@alleyinteractive/stylelint-config"
+}

README.md

@@ -11,9 +11,7 @@ for use when submoduling a plugin. The built branches will include Composer
 dependencies and any compiled front-end assets (if using them).
 
 The plugin supports front-end assets which can be enqueued inside
-`src/assets.php`. For plugins that don't require front-end assets, the
-configuration script below will prompt you to delete the front-end files if you
-don't wish to use them.
+`src/assets.php` or from within an entry points `index.php` file. For plugins that don't require front-end assets, the configuration script below will prompt you to delete the front-end files if you don't wish to use them.
 
 ## Getting Started
 
@@ -74,24 +72,44 @@ Run `npm run lint` to run ESLint against all JavaScript files. Linting will also
 happen when running development or production builds.
 
 Run `composer test` to run tests against PHPUnit and the PHP code in the plugin.
-## Updating Dependencies
 
-To update `@wordpress` dependencies, simply execute:
+### The `entries` directory and entry points
+All directories created in the `entries` directory can serve as entry points and will be compiled with [@wordpress/scripts](https://github.com/WordPress/gutenberg/blob/trunk/packages/scripts/README.md#scripts) into the `build` directory with an accompanied `index.asset.php` asset map.
+
+#### Enqueuing Entry Points
+
+You can also include an `index.php` file in the entry point directory for enqueueing or registering a script. This file will then be moved to the build directory and will be auto-loaded with the `load_scripts()` function in the `functions.php` file. Alternatively, if a script is to be enqueued elsewhere there are helper functions in the `src/assets.php` file for getting the assets.
+
+### Scaffold a block with `create-block`
+
+Use the `create-block` command to create custom blocks with [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) and follow the prompts to generate all the block assets in the `blocks/` directory. 
+Block registration, script creation, etc will be scaffolded from the `bin/create-block/templates/block/` templates. Run `npm run build` to compile and build the custom block. Blocks are enqueued using the `load_scripts()` function in `src/assets.php`.
+
+### Updating WP Dependencies
+
+Updates the [WordPress dependency packages](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#packages-update) used in the project to their latest version.
+
+To update `@wordpress` dependencies to their latest version use the packages-update command:
+
+```sh
+npm run packages-update
+```
+
+This script provides the following custom options:
+
+-   `--dist-tag` – allows specifying a custom dist-tag when updating npm packages. Defaults to `latest`. This is especially useful when using [`@wordpress/dependency-extraction-webpack-plugin`](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin). It lets installing the npm dependencies at versions used by the given WordPress major version for local testing, etc. Example:
 
 ```sh
-npm run update-dependencies WPVERSION
+npm run packages-update --dist-tag=wp-WPVERSION`
 ```
 
 Where `WPVERSION` is the version of WordPress you are targeting. The version
-must include both the major and patch version (e.g., `5.9.3`). For example:
+must include both the major and minor version (e.g., `6.1`). For example:
 
 ```sh
-npm run update-dependencies 5.9.3
+npm run packages-update --dist-tag=wp-6.1`
 ```
 
-The versions are drawn from tags on
-[wordpress-develop](https://github.com/WordPress/wordpress-develop/tags).
-<!--/front-end-->
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

babel.config.js

@@ -0,0 +1,14 @@
+/**
+ * This babel config is used by Jest to ensure that tests
+ * will run correctly in Typescript and JavaScript files.
+ *
+ * Jest supports TypeScript, via Babel.
+ *
+ * @see https://jestjs.io/docs/getting-started#using-typescript
+ */
+module.exports = {
+  presets: [
+    '@babel/preset-env',
+    '@wordpress/babel-preset-default',
+  ],
+};

bin/create-block/index.js

@@ -0,0 +1,24 @@
+const path = require('path');
+
+/**
+ * Custom Variables and templates for scaffolding blocks.
+ * @see https://github.com/WordPress/gutenberg/blob/trunk/packages/create-block/docs/external-template.md#external-project-templates
+ */
+module.exports = {
+  defaultValues: {
+    namespace: 'create-wordpress-plugin',
+    plugin: false,
+    description: '',
+    dashicon: 'palmtree',
+    category: 'widgets',
+    editorScript: 'file:index.js',
+    editorStyle: 'file:index.css',
+    style: ['file:style-index.css'],
+    render: 'file:render.php',
+  },
+  variants: {
+    static: {},
+    dynamic: {},
+  },
+  blockTemplatesPath: path.join(__dirname, 'templates', 'block'),
+};

bin/create-block/templates/block/edit.jsx.mustache

@@ -0,0 +1,38 @@
+/**
+ * Retrieves the translation of text.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * React hook that is used to mark the block wrapper element.
+ * It provides all the necessary props like the class name.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
+ */
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
+ * Those files can contain any CSS code that gets applied to the editor.
+ *
+ * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
+ */
+import './index.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
+ *
+ * @return {WPElement} Element to render.
+ */
+export default function Edit() {
+  return (
+    <p {...useBlockProps()}>
+      { __('Block Title – hello from the editor!', 'create-wordpress-plugin') }
+    </p>
+  );
+}

bin/create-block/templates/block/index.js.mustache

@@ -0,0 +1,42 @@
+/**
+ * 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';
+{{#isStaticVariant}}
+import save from './save';
+{{/isStaticVariant}}
+import metadata from './block.json';
+{{#isAnotherVariant}}
+console.log('it worked');
+{{/isAnotherVariant}}
+
+/**
+ * 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,
+  {
+    edit,
+    {{#isStaticVariant}}
+    save,
+    {{/isStaticVariant}}
+  },
+);

bin/create-block/templates/block/index.php.mustache

@@ -0,0 +1,22 @@
+<?php
+/**
+ * Block Name: {{title}}.
+ *
+ * @package create-wordpress-plugin
+ */
+
+/**
+ * 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 {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
+	// Register the block by passing the location of block.json.
+	register_block_type(
+		__DIR__
+	);
+
+}
+add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );

bin/create-block/templates/block/index.scss.mustache

@@ -0,0 +1,13 @@
+/**
+ * The following styles get applied inside the editor only.
+ *
+ * All imported CSS files are bundled into one chunk named after the entry point,
+ * which defaults to index.js, and thus the file created becomes index.css.
+ * This is for styles used only in the editor.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-{{namespace}}-{{slug}} {
+  border: 1px dotted #f00;
+}

bin/create-block/templates/block/render.php.mustache

@@ -0,0 +1,17 @@
+{{#isDynamicVariant}}
+<?php
+/**
+ * All of the parameters passed to the function where this file is being required are accessible in this scope:
+ *
+ * @param array    $attributes     The array of attributes for this block.
+ * @param string   $content        Rendered block output. ie. <InnerBlocks.Content />.
+ * @param WP_Block $block_instance The instance of the WP_Block class that represents the block being rendered.
+ *
+ * @package create-wordpress-plugin
+ */
+
+?>
+<p <?php echo wp_kses_data( get_block_wrapper_attributes() ); ?>>
+	<?php esc_html_e( '{{title}} – hello from a dynamic block!', 'create-wordpress-plugin' ); ?>
+</p>
+{{/isDynamicVariant}}

bin/create-block/templates/block/save.jsx.mustache

@@ -0,0 +1,26 @@
+{{#isStaticVariant}}
+/**
+ * React hook that is used to mark the block wrapper element.
+ * It provides all the necessary props like the class name.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
+ */
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * 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`.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#save
+ *
+ * @return {WPElement} Element to render.
+ */
+export default function save() {
+  return (
+    <p { ...useBlockProps.save() }>
+      { '{{title}} – hello from the saved content!' }
+    </p>
+  );
+}
+{{/isStaticVariant}}

bin/create-block/templates/block/style.scss.mustache

@@ -0,0 +1,18 @@
+/**
+ * The following styles get applied both on the front of your site
+ * and in the editor.
+ *
+ * Imported style.css file(s) (applies to SASS and SCSS extensions)
+ * get bundled into one style-index.css file that is meant to be
+ * used both on the front-end and in the editor.
+ *
+ * Replace them with your own styles or remove the file completely.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#block-styles
+ */
+
+.wp-block-{{namespace}}-{{slug}} {
+  background-color: #21759b;
+  color: #fff;
+  padding: 2px;
+}