@emulsify/core 3.5.0 → 4.0.1

package/.cli/init.js

@@ -1,26 +1,36 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
+/**
+ * @file Initializes a generated Emulsify project from project.emulsify.json.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /**
- * 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 = () => {
+  const configPath = path.join(__dirname, '../config/project.emulsify.json');
+
   try {
-    return require('../config/project.emulsify.json');
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
   } catch (e) {
     throw new Error(
       `Unable to load an Emulsify project config file (project.emulsify.json): ${String(
@@ -31,9 +41,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,11 +80,10 @@ 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 }) =>
@@ -80,24 +91,23 @@ const renameFiles = (files) =>
   );
 
 /**
- * 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 +121,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 +151,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 +161,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) => {

package/.storybook/_drupal.js

@@ -1,10 +1,96 @@
-// Simple Drupal.behaviors usage for Storybook
+/**
+ * @file Drupal browser compatibility layer for Storybook.
+ */
+
+const emulsifyEnv =
+  (typeof __EMULSIFY_ENV__ !== 'undefined' && __EMULSIFY_ENV__) || {};
+const projectMachineName =
+  typeof emulsifyEnv.machineName === 'string' ? emulsifyEnv.machineName : '';
+
+/**
+ * Storybook-safe defaults for the Drupal settings object.
+ *
+ * These values cover the common browser properties Drupal-authored JavaScript
+ * reads while keeping project-specific module settings in project overrides.
+ *
+ * @type {object}
+ */
+const defaultDrupalSettings = {
+  path: {
+    baseUrl: '/',
+    currentLanguage: 'en',
+    isFront: false,
+    langcode: 'en',
+    pathPrefix: '',
+    currentPath: '/',
+    currentPathIsAdmin: false,
+  },
+  user: {
+    uid: 0,
+    permissionsHash: '',
+  },
+  ajaxPageState: {
+    theme: projectMachineName,
+    theme_token: '',
+  },
+  ajaxTrustedUrl: {},
+  pluralDelimiter: '\u0003',
+};
+
+/**
+ * Determine whether a value can be recursively merged as settings.
+ *
+ * @param {*} value - Candidate value.
+ * @returns {boolean} TRUE when the value is a plain object.
+ */
+function isPlainObject(value) {
+  return (
+    Boolean(value) &&
+    Object.prototype.toString.call(value) === '[object Object]'
+  );
+}
+
+/**
+ * Merge default settings with project-provided Drupal settings.
+ *
+ * Existing project settings win so projects can provide module-specific values
+ * or override neutral defaults from `config/emulsify-core/storybook/preview.js`.
+ *
+ * @param {object} defaults - Default Drupal settings.
+ * @param {object} overrides - Project-provided Drupal settings.
+ * @returns {object} Merged settings object.
+ */
+function mergeDrupalSettings(defaults, overrides) {
+  const merged = { ...defaults };
+
+  for (const [key, value] of Object.entries(overrides || {})) {
+    // Drupal settings keys are project/module-defined by design.
+    // eslint-disable-next-line security/detect-object-injection
+    const defaultValue = merged[key];
+    const nextValue =
+      isPlainObject(defaultValue) && isPlainObject(value)
+        ? mergeDrupalSettings(defaultValue, value)
+        : value;
+
+    // Drupal settings keys are project/module-defined by design.
+    // eslint-disable-next-line security/detect-object-injection
+    merged[key] = nextValue;
+  }
+
+  return merged;
+}
 
 /**
- * Global Drupal namespace stub for Storybook environment.
+ * Create the global Drupal namespace stub for the Storybook environment.
+ *
  * @namespace Drupal
  */
-window.Drupal = { behaviors: {} };
+window.Drupal = window.Drupal || {};
+window.Drupal.behaviors = window.Drupal.behaviors || {};
+window.drupalSettings = mergeDrupalSettings(
+  defaultDrupalSettings,
+  isPlainObject(window.drupalSettings) ? window.drupalSettings : {},
+);
 
 /**
  * Immediately-Invoked Function Expression to scope Drupal behavior attachment logic.
@@ -12,6 +98,38 @@ window.Drupal = { behaviors: {} };
  * @param {Object} drupalSettings - Global Drupal settings object stub.
  */
 (function (Drupal, drupalSettings) {
+  /**
+   * Replaces Drupal-style string placeholders without translating the string.
+   *
+   * @param {string} str - String containing placeholders such as `@name`.
+   * @param {Object.<string, string|number>} [args={}] - Placeholder values.
+   * @returns {string} Formatted string.
+   */
+  Drupal.formatString =
+    Drupal.formatString ||
+    function (str, args = {}) {
+      let formatted = String(str);
+
+      for (const [placeholder, replacement] of Object.entries(args || {})) {
+        formatted = formatted.split(placeholder).join(String(replacement));
+      }
+
+      return formatted;
+    };
+
+  /**
+   * Minimal translation shim for Drupal-authored JavaScript in Storybook.
+   *
+   * @param {string} str - Source string.
+   * @param {Object.<string, string|number>} [args={}] - Placeholder values.
+   * @returns {string} Formatted source string.
+   */
+  Drupal.t =
+    Drupal.t ||
+    function (str, args = {}) {
+      return Drupal.formatString(str, args);
+    };
+
   /**
    * Throws an error asynchronously to avoid interrupting execution flow.
    * @param {Error} error - The error object to throw.
@@ -32,11 +150,14 @@ window.Drupal = { behaviors: {} };
   Drupal.attachBehaviors = function (context, settings) {
     context = context || document;
     settings = settings || drupalSettings;
-    /** @type {Array<{attach?: Function}>} */
-    const behaviors = Object.values(Drupal.behaviors);
+    /** @type {Object.<string, {attach: Function}>} */
+    const behaviors = Drupal.behaviors;
 
-    // Iterate through each behavior and invoke its attach method if defined.
-    behaviors.forEach(function (behavior) {
+    // Attach each registered behavior while isolating individual failures.
+    Object.keys(behaviors).forEach(function (behaviorName) {
+      // Drupal behavior names are project/module-defined by design.
+      // eslint-disable-next-line security/detect-object-injection
+      const behavior = behaviors[behaviorName];
       if (typeof behavior.attach === 'function') {
         try {
           behavior.attach(context, settings);
@@ -46,4 +167,4 @@ window.Drupal = { behaviors: {} };
       }
     });
   };
-})(Drupal, window.drupalSettings);
+})(window.Drupal, window.drupalSettings);

package/.storybook/css-components.js

@@ -0,0 +1,13 @@
+/**
+ * @file Storybook mirrored component CSS side-effect loader.
+ *
+ * Drupal projects load component CSS from the mirrored root components tree,
+ * but shared/global Storybook CSS still lives under dist. Exclude
+ * dist/components so the mirrored component CSS is not loaded twice.
+ */
+
+import.meta.glob('../../../../components/**/*.css', { eager: true });
+import.meta.glob(
+  ['../../../../dist/**/*.css', '!../../../../dist/components/**/*.css'],
+  { eager: true },
+);

package/.storybook/css-dist.js

@@ -0,0 +1,5 @@
+/**
+ * @file Storybook compiled dist CSS side-effect loader.
+ */
+
+import.meta.glob('../../../../dist/**/*.css', { eager: true });

package/.storybook/emulsifyTheme.js

@@ -1,16 +1,21 @@
-// Documentation on theming Storybook: https://storybook.js.org/docs/configurations/theming/
+/**
+ * @file Default Emulsify theme for the Storybook manager UI.
+ *
+ * @see https://storybook.js.org/docs/configurations/theming/
+ */
+
 import { create } from 'storybook/theming';
 
 export default create({
   base: 'dark',
 
-  // UI
+  // Storybook application chrome colors.
   appBg: '#00405B',
   appContentBg: '#00202E',
   appBorderColor: '#00405B',
   appBorderRadius: 4,
 
-  // Typography
+  // Typography is intentionally aligned with the design system brand.
   fontBase: '"Mona Sans", sans-serif',
   fontCode: 'monospace',
 
@@ -29,9 +34,7 @@ export default create({
   inputBorder: '#00405B',
   inputTextColor: 'white',
   inputBorderRadius: 4,
-  // Branding
+  // Branding links the manager back to the public Emulsify site.
   brandTitle: 'Emulsify',
   brandUrl: 'https://emulsify.info',
-  brandImage:
-    'https://raw.githubusercontent.com/fourkitchens/emulsify-core/main/assets/images/emulsify-logo-sb.svg',
 });