Release: 4.x (Vite and Storybook React v10)

.cli/init.js

@@ -1,22 +1,27 @@
 #!/usr/bin/env node
 
+/**
+ * @file Initializes a generated Emulsify project from project.emulsify.json.
+ */
+
 const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 
 /**
- * Returns a boolean indicating whether or not the given object is a literal object.
+ * Determine whether a value is a plain object.
  *
- * @param {any} obj object who's type will be checked.
- * @returns {boolean} boolean indicating whether or not the given obj is a literal object.
+ * @param {*} obj - Value to inspect.
+ * @returns {boolean} TRUE when the value is a plain object.
  */
 const isObjectLiteral = (obj) =>
   obj != null && obj.constructor.name === 'Object';
 
 /**
- * Attempts to require the project.emulsify.json file.
+ * Load project.emulsify.json from the generated project config directory.
  *
- * @returns parsed project.emulsify.json file.
+ * @returns {Object} Parsed project.emulsify.json file.
+ * @throws {Error} When the config cannot be loaded.
  */
 const getEmulsifyConfig = () => {
   try {
@@ -31,9 +36,11 @@ const getEmulsifyConfig = () => {
 };
 
 /**
- * Throws if the given emulsify config file is invalid.
+ * Validate the minimal project configuration required for initialization.
  *
- * @param {*} config emulsify project config, as loaded from a project.emulsify.json file.
+ * @param {*} config - Emulsify project config loaded from project.emulsify.json.
+ * @returns {void}
+ * @throws {Error} When required config values are missing or invalid.
  */
 const validateEmulsifyConfig = (config) => {
   const prefix = 'Invalid project.emulsify.json config file';
@@ -68,36 +75,34 @@ const validateEmulsifyConfig = (config) => {
 };
 
 /**
- * Takes an array of objects describing the origin and destination of a given file,
- * then moves each specified file according to it's to/from properties.
+ * Move generated starter files to their project-specific names.
  *
- * @param {Array<{ to: string, from: string }>} files array of objects depicting the origin and destination of a given file.
- * @returns void.
+ * @param {Array<{ to: string, from: string }>} files - Files to move.
+ * @returns {Array<void>} Rename results.
  */
 const renameFiles = (files) =>
   files.map(({ from, to }) =>
     fs.renameSync(path.join(__dirname, from), path.join(__dirname, to)),
   );
 
 /**
- * Takes a machineName, and returns a fn that, when called with a str,
- * replaces all instances of `emulsify` with the given machineName.
+ * Create a replacer that swaps the starter machine name for the project name.
  *
- * @param {string} machineName string that should replace emulsify.
- * @returns {function} fn that when called with a str, replaces all instances of `emulsify` with the given machineName.
+ * @param {string} machineName - Machine name that should replace `emulsify`.
+ * @returns {Function} String replacer.
  */
 const strReplaceEmulsify = (machineName) => (str) =>
   str.replace(/emulsify/g, machineName);
 
 /**
- * Loads a yml file at filePath, applies the functor to the contents of the file, and writes it.
+ * Load a YAML file, transform its parsed contents, and write it back.
  *
- * @param {string} filePath path to the file that should be loaded, modified, and re-saved.
- * @param {fn} functor fn that should return the new contents of the file, to be saved.
- * @returns void.
+ * @param {string} filePath - File to load, modify, and save.
+ * @param {Function} functor - Function that returns the replacement YAML data.
+ * @returns {void}
  */
 const applyToYmlFile = (filePath, functor) => {
-  if (!filePath || typeof filePath !== `string`) {
+  if (!filePath || typeof filePath !== 'string') {
     throw new Error(
       `Cannot modify a file without knowing how to access it: ${filePath}`,
     );
@@ -111,18 +116,17 @@ const applyToYmlFile = (filePath, functor) => {
 };
 
 const main = () => {
-  // Load up config file, throw if none exists.
+  // Load the project config before mutating any generated files.
   const config = getEmulsifyConfig();
 
-  // Validate config file, throw if it is missing
-  //properties or is otherwise malformed.
+  // Fail fast when required project metadata is missing or malformed.
   validateEmulsifyConfig(config);
 
   const {
-    project: { machineName, name },
+    project: { machineName },
   } = config;
 
-  // Move all files to their correct location.
+  // Rename starter files from the generic prefix to the project machine name.
   renameFiles([
     {
       from: '../emulsify.info.yml',
@@ -142,7 +146,7 @@ const main = () => {
     },
   ]);
 
-  // Update info.yml file.
+  // Update info.yml values that Drupal reads from the generated theme.
   applyToYmlFile(
     path.join(__dirname, `../${machineName}.info.yml`),
     (info) => ({
@@ -152,7 +156,7 @@ const main = () => {
     }),
   );
 
-  // Update breakpoint.yml file.
+  // Update breakpoint keys to match the renamed theme machine name.
   applyToYmlFile(
     path.join(__dirname, `../${machineName}.breakpoints.yml`),
     (breakpoints) => {

.editorconfig

@@ -1,4 +1,4 @@
-# Unix-style newlines with a newline ending every file
+# Keep editor defaults aligned with Prettier and repository formatting.
 [*]
 indent_style = space
 indent_size = 2

.github/ISSUE_TEMPLATE/BUG_REPORT_TEMPLATE.md

@@ -1,18 +1,24 @@
 ### Describe the bug
+
 _A clear and concise description of what the bug is._
 
 ### Steps to reproduce the bug
+
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
 ### Expected behavior
+
 A clear and concise description of what you expected to happen.
 
 ### Suggested solution or approach:
+
 _(optional) Describe a solution or approach to your request that may help with implementation._
 
 ### Additional context
-_(optional) Add any other context or screenshots about the feature request here._
+
+_(optional) Add any other context or screenshots about the feature request here._

.github/ISSUE_TEMPLATE/FEATURE_REQUEST_TEMPLATE.md

@@ -1,11 +1,15 @@
 ### Emulsify Core Version:
+
 - [1.0.0](https://github.com/emulsify-ds/emulsify-core/releases)):
 
 ### Description of the feature request:
-_Please give as much information as possible_ 
+
+_Please give as much information as possible_
 
 ### Suggested solution or approach:
+
 _(optional) Describe a solution or approach to your request that may help with implementation._
 
 ### Additional context:
-_(optional) Add any other context or screenshots about the feature request here._
+
+_(optional) Add any other context or screenshots about the feature request here._

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,19 +1,24 @@
 **This PR does the following:**
+
 - Adds functionality bullet item
 - Fixes this or that bullet item
-  
+
 ### Related Issue(s)
+
 - [Title of the issue](https://github.com/emulsify-ds/emulsify-core/issues/1)
 
 ### Notes:
+
 - (optional) Document any intentionally unfinished parts or known issues within this PR
 
 ### Functional Testing:
+
 - [ ] Document steps that allow someone to fully test your code changes. Include screenshot and links when appropriate.
 
 ### Security
+
 _Security checks that should be reviewed_
 
 ### Accessibility
-_Should this be checked for this feature?_
 
+_Should this be checked for this feature?_

.github/dependabot.yml

@@ -1,6 +1,8 @@
+# Keeps npm dependency metadata current for the package root.
 version: 2
 updates:
   - package-ecosystem: npm
-    directory: "/"
+    directory: '/'
+    # Weekly updates reduce churn while keeping dependencies maintained.
     schedule:
       interval: weekly

.github/fixtures/release/drupal-sdc-src-components/project.emulsify.json

@@ -0,0 +1,8 @@
+{
+  "project": {
+    "platform": "drupal",
+    "name": "drupal-sdc-src-components",
+    "machineName": "drupal_sdc_src_components",
+    "singleDirectoryComponents": true
+  }
+}

.github/fixtures/release/drupal-sdc-src-components/src/components/card/_content.twig

@@ -0,0 +1 @@
+<p>{{ content }}</p>

.github/fixtures/release/drupal-sdc-src-components/src/components/card/card.asset.txt

@@ -0,0 +1 @@
+drupal-sdc-asset

.github/fixtures/release/drupal-sdc-src-components/src/components/card/card.component.yml

@@ -0,0 +1,3 @@
+name: Card
+props:
+  type: object

.github/fixtures/release/drupal-sdc-src-components/src/components/card/card.js

@@ -0,0 +1,6 @@
+import template from './card.twig';
+
+export default template({
+  heading: 'Drupal SDC card',
+  content: 'Rendered from a Twig include.',
+});

.github/fixtures/release/drupal-sdc-src-components/src/components/card/card.scss

@@ -0,0 +1,3 @@
+.card {
+  color: #135e96;
+}

.github/fixtures/release/drupal-sdc-src-components/src/components/card/card.twig

@@ -0,0 +1,8 @@
+{% set attrs = {
+  class: bem('card', ['featured']),
+  'data-fixture': 'drupal-sdc'
+} %}
+<article {{ add_attributes(attrs) }}>
+  <h2>{{ heading }}</h2>
+  {% include './_content.twig' %}
+</article>

.github/fixtures/release/generic-src-components/config/emulsify-core/vite/plugins.js

@@ -0,0 +1,12 @@
+module.exports = [
+  {
+    name: 'generic-fixture-vite-extension',
+    generateBundle() {
+      this.emitFile({
+        type: 'asset',
+        fileName: 'extension-marker.txt',
+        source: 'config/emulsify-core/vite/plugins.js loaded\n',
+      });
+    },
+  },
+];

.github/fixtures/release/generic-src-components/project.emulsify.json

@@ -0,0 +1,7 @@
+{
+  "project": {
+    "platform": "generic",
+    "name": "generic-src-components",
+    "machineName": "generic_src_components"
+  }
+}

.github/fixtures/release/generic-src-components/src/base/base.js

@@ -0,0 +1 @@
+export const fixture = 'generic base';

.github/fixtures/release/generic-src-components/src/base/base.scss

@@ -0,0 +1,3 @@
+.base {
+  color: #2f6f4e;
+}

.github/fixtures/release/generic-src-components/src/components/card/_content.twig

@@ -0,0 +1 @@
+<p>{{ content }}</p>

.github/fixtures/release/generic-src-components/src/components/card/card.asset.txt

@@ -0,0 +1 @@
+generic-src-asset

.github/fixtures/release/generic-src-components/src/components/card/card.js

@@ -0,0 +1,6 @@
+import template from './card.twig';
+
+export const html = template({
+  heading: 'Generic Twig card',
+  content: 'Compiled with generic platform behavior.',
+});

.github/fixtures/release/generic-src-components/src/components/card/card.scss

@@ -0,0 +1,3 @@
+.card {
+  color: #4f5f9f;
+}

.github/fixtures/release/generic-src-components/src/components/card/card.twig

@@ -0,0 +1,8 @@
+{% set attrs = {
+  class: bem('card', ['generic']),
+  'data-fixture': 'generic-src'
+} %}
+<article {{ add_attributes(attrs) }}>
+  <h2>{{ heading }}</h2>
+  {% include './_content.twig' %}
+</article>

.github/fixtures/release/large-twig-storybook/project.emulsify.json

@@ -0,0 +1,7 @@
+{
+  "project": {
+    "platform": "generic",
+    "name": "large-twig-storybook",
+    "machineName": "large_twig_storybook"
+  }
+}

.github/fixtures/release/large-twig-storybook/src/components/gallery/gallery.stories.js

@@ -0,0 +1,13 @@
+import { renderTwig } from '@emulsify/core/storybook';
+import template from './gallery.twig';
+
+export default {
+  title: 'Fixtures/Large Twig Storybook',
+};
+
+export const Default = {
+  render: renderTwig(template),
+  args: {
+    heading: 'Large Twig fixture',
+  },
+};

.github/fixtures/release/large-twig-storybook/src/components/gallery/gallery.twig

@@ -0,0 +1,8 @@
+<section class="large-gallery">
+  <h2>{{ heading }}</h2>
+  {{ include('@components/item-001/item-001.twig', {
+    label: 'Included via normalized namespace',
+    variant: 'featured'
+  }) }}
+  <pre data-source-check>{{ source('@components/item-002/item-002.twig') }}</pre>
+</section>

.github/fixtures/release/legacy-components/components/banner/banner.asset.txt

@@ -0,0 +1 @@
+legacy-components-asset

.github/fixtures/release/legacy-components/components/banner/banner.js

@@ -0,0 +1,5 @@
+import template from './banner.twig';
+
+export default template({
+  heading: 'Legacy banner',
+});