Feature: Rapid UI component scaffolding

themes/10up-theme/README.md

@@ -106,3 +106,24 @@ You can activate `ct.css` on any page load by including `?debug_perf=1` in the U
 Considering we do not want to load script everywhere throughout the theme, we have provided engineeers with a way to trigger the `ct.css` output by using a query param.
 
 <sub>* for 10uppers, reach out to Daine for any questions / guidance / support in regards to `ct.css`</sub>
+
+
+# UI Component Generation
+The theme now includes a micro-generator framework [plop](https://plopjs.com/documentation/) to rapidly create UI components.
+
+From /wp-content `npm run new -w=tenup-theme` (replacing tenup-theme with your theme workspace as appropriate)
+
+Follow the guided menu to generate component files in a consistent manner:
+
+- component partial
+- styleguide example(s) of the partial
+- component CSS
+- component JS
+
+All files are optional so you can be as granular as you like.
+
+Including the generated files needs to be done manually in the respective index files and/or styleguide template.
+
+Plop uses [handlebars](https://handlebarsjs.com/) template files to format the output, if you're not a fan of the opinions set in the defaults, these can be altered in *[theme]/plop-templates*.
+
+If you would like to extend the generator (perhaps to alter optional atomic structure options), the config files lives at *[theme]/plopfile.js*.

themes/10up-theme/assets/css/frontend/base/button.css

@@ -8,4 +8,5 @@
  */
 button:where(:not(.components-button)) {
 
+	/* TODO */
 }

themes/10up-theme/assets/css/frontend/base/link.css

@@ -8,4 +8,5 @@
  */
 a:where(:not(.components-external-link)) {
 
+	/* TODO */
 }

themes/10up-theme/assets/css/frontend/components/example-ui-component/example-ui-component.css

@@ -0,0 +1,8 @@
+/*
+ * Example ui component Frontend styles
+ */
+
+.example-ui-component {
+
+	/* TODO */
+}

themes/10up-theme/assets/css/frontend/components/example-ui-component/index.css

@@ -0,0 +1 @@
+@import url("example-ui-component");

themes/10up-theme/assets/css/frontend/components/index.css

@@ -1,2 +1,4 @@
 /* Components */
+
+/* @import url("example-ui-component"); */
 @import url("skip-to-content-link.css");

themes/10up-theme/assets/css/styleguide/styleguide.css

@@ -174,6 +174,21 @@
 	margin-bottom: 1em;
 }
 
+.uikit__section > .content > .sub-heading {
+	box-sizing: border-box;
+	color: var(--c-uikit-accent);
+	font-size: 14px;
+	font-weight: 400;
+	width: 100%;
+}
+
+.uikit__section > .content > .sub-heading::after,
+.uikit__section > .content > .sub-heading::before {
+	content: " -";
+	display: inline-block;
+	margin: 0 0 0 0.5em;
+}
+
 @media (--bp-uikit-small) {
 
 	.uikit__section > .heading {

themes/10up-theme/assets/js/frontend/components/example-ui-component/example-ui-component.js

@@ -0,0 +1,18 @@
+import FindExampleUiComponent from './find-example-ui-component';
+
+/**
+ * Example ui component
+ *
+ * Add a description here
+ *
+ * @returns {void}
+ */
+const ExampleUiComponent = () => {
+	if (!FindExampleUiComponent()) {
+		return;
+	}
+
+	console.log('TODO: Example ui component');
+};
+
+export default ExampleUiComponent;

themes/10up-theme/assets/js/frontend/components/example-ui-component/find-example-ui-component.js

@@ -0,0 +1,22 @@
+// Reference to the DOM element to ensure we don't search multiple times
+let $elementRef = null;
+
+// DRY re-usable component naming e.g. to create new DOM elements with BEM naming
+export const EXAMPLE_UI_COMPONENT_CLASSNAME = 'example-ui-component';
+
+/**
+ * FindExampleUiComponent
+ *
+ * Used to identify or determine presence of the element in the DOM
+ * - e.g. DRY selectors for dynamic imports
+ * - e.g. DRY selectors for initialisation checks
+ *
+ * @returns {HTMLElement} the DOM element we are looking for
+ */
+const FindExampleUiComponent = () => {
+	$elementRef = $elementRef ?? document.querySelector(`.example-ui-component`);
+
+	return $elementRef;
+};
+
+export default FindExampleUiComponent;

themes/10up-theme/assets/js/frontend/components/example-ui-component/index.js

@@ -0,0 +1 @@
+export { default } from './example-ui-component';

themes/10up-theme/assets/js/frontend/frontend.js

@@ -1,3 +1,3 @@
 import '../../css/frontend/style.css';
 
-// import foo from './components/bar';
+// import ExampleUiComponent from './components/example-ui-component';

themes/10up-theme/composer.json

@@ -8,7 +8,8 @@
     }
   ],
   "require": {
-    "php": ">=7.0"
+    "php": ">=7.0",
+    "fzaninotto/faker": "^1.9.2"
   },
   "autoload": {
     "psr-4": {

themes/10up-theme/package.json

@@ -9,13 +9,15 @@
     "lint-js": "10up-toolkit lint-js",
     "lint-style": "10up-toolkit lint-style",
     "test": "10up-toolkit test-unit-jest",
-    "clean-dist": "rm -rf ./dist"
+    "clean-dist": "rm -rf ./dist",
+    "new": "plop"
   },
   "engines": {
     "node": ">=12.0.0"
   },
   "devDependencies": {
-    "10up-toolkit": "^4.1.1"
+    "10up-toolkit": "^4.1.1",
+    "plop": "^3.0.5"
   },
   "dependencies": {
     "normalize.css": "^8.0.1"

themes/10up-theme/partials/example-ui-component/example-ui-component.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * Example ui component Partial
+ *
+ * @package TenUpTheme
+ */
+
+// Add default values for ALL args here
+$arg_defaults = [
+	// Additional classes can be passed through for edge case management
+	'class_names' => '',
+];
+$args         = wp_parse_args( $args, $arg_defaults );
+
+// Provides a final check to render the component or not
+$should_render = true;
+// The partial name - corresponds to naming used in CSS - used to build out child classnames (BEM)
+$partial_name = 'example-ui-component';
+
+// Extend this (.=) later on with variant specific classes if needed
+$container_class_names = $args['class_names'];
+
+// Bail early if there are any conditions that should prevent rendering
+if ( ! $should_render ) {
+	return;
+}
+?>
+<div class="<?php echo esc_attr( "{$partial_name} {$container_class_names}" ); ?>">
+	<div class="<?php echo esc_attr( "{$partial_name}__inner" ); ?>">
+		Partial: Example ui component goes here
+	</div>
+</div>

themes/10up-theme/partials/example-ui-component/styleguide/example-default.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Example ui component Styleguide Example - Default - Partial
+ *
+ * @package TenUpTheme
+ */
+
+// phpcs:disable WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
+$faker = Faker\Factory::create();
+
+/*
+ * Use this to setup a specific example of the component
+ * for inclusion in the styleguide
+ *  - Don't forget to include new variants of this partial in ./examples.php
+ *    - using the $name param (currently null) to match the filename suffix
+ *
+ * Faker is a PHP library that generates fake data for you.
+ * https://github.com/fzaninotto/Faker
+ *
+ * For images a better alternative is usually
+ * https://picsum.photos
+ *
+ * For illustrations you may want to consider
+ * https://doodleipsum.com/
+ *
+ */
+?>
+<h3 class="sub-heading">Variation: Default</h3>
+<?php
+	get_template_part(
+		'partials/example-ui-component/example-ui-component',
+		null,
+		[
+			'class_names' => '',
+		]
+	);
+	?>

themes/10up-theme/partials/example-ui-component/styleguide/examples.php

@@ -0,0 +1,24 @@
+<?php
+/**
+ * Example ui component Styleguide Index - Partial
+ *
+ * @package TenUpTheme
+ */
+
+/*
+ * Use this to include ALL the example variations you think we should demonstrate
+ * Don't forget to include this partial in [theme]/templates/page-styleguide.php
+ */
+?>
+<section class="uikit__section" id="example-ui-component">
+	<h2 class="heading">: Example ui component</h2>
+	<div class="content">
+		<?php
+			get_template_part(
+				'partials/example-ui-component/styleguide/example',
+				'default'
+			);
+			?>
+	</div>
+</section>
+

themes/10up-theme/plop-templates/ui-component-css-index.hbs

@@ -0,0 +1 @@
+@import url("{{ kebabCase name }}");

themes/10up-theme/plop-templates/ui-component-css.hbs

@@ -0,0 +1,8 @@
+/*
+ * {{ sentenceCase name }} Frontend styles
+ */
+
+.{{ kebabCase name }} {
+
+	/* TODO */
+}

themes/10up-theme/plop-templates/ui-component-js-find.hbs

@@ -0,0 +1,22 @@
+// Reference to the DOM element to ensure we don't search multiple times
+let $elementRef = null;
+
+// DRY re-usable component naming e.g. to create new DOM elements with BEM naming
+export const {{ constantCase name }}_CLASSNAME = '{{ kebabCase name }}';
+
+/**
+ * Find{{ pascalCase name }}
+ *
+ * Used to identify or determine presence of the element in the DOM
+ * - e.g. DRY selectors for dynamic imports
+ * - e.g. DRY selectors for initialisation checks
+ *
+ * @returns {HTMLElement} the DOM element we are looking for
+ */
+const Find{{ pascalCase name }} = () => {
+	$elementRef = $elementRef ?? document.querySelector(`.{{ kebabCase name }}`);
+
+	return $elementRef;
+};
+
+export default Find{{ pascalCase name }};

themes/10up-theme/plop-templates/ui-component-js-index.hbs

@@ -0,0 +1 @@
+export { default } from './{{ kebabCase name }}';

themes/10up-theme/plop-templates/ui-component-js.hbs

@@ -0,0 +1,18 @@
+import Find{{ pascalCase name }} from './find-{{ kebabCase name }}';
+
+/**
+ * {{ sentenceCase name }}
+ *
+ * Add a description here
+ *
+ * @returns {void}
+ */
+const {{ pascalCase name }} = () => {
+	if (!Find{{ pascalCase name }}()) {
+		return;
+	}
+
+	console.log('TODO: {{ sentenceCase name }}');
+};
+
+export default {{ pascalCase name }};