@emulsify/core 2.7.0 → 3.0.1

package/.storybook/webpack.config.js

@@ -1,30 +1,67 @@
-const path = require('path');
-const globImporter = require('node-sass-glob-importer');
+import { dirname, resolve } from 'path';
+import globImporter from 'node-sass-glob-importer';
+import _StyleLintPlugin from 'stylelint-webpack-plugin';
+import ESLintPlugin from 'eslint-webpack-plugin';
+import resolves from '../config/webpack/resolves.js';
+import emulsifyConfig from '../../../../project.emulsify.json' with { type: 'json' };
 
-const _StyleLintPlugin = require('stylelint-webpack-plugin');
-const ESLintPlugin = require('eslint-webpack-plugin');
-const resolves = require('../config/webpack/resolves');
+// Create __filename from import.meta.url without fileURLToPath
+let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
 
-// Emulsify project configuration.
-const emulsifyConfig = require('../../../../project.emulsify.json');
+// On Windows, remove the leading slash (e.g. "/C:/path" -> "C:/path")
+if (process.platform === 'win32' && _filename.startsWith('/')) {
+  _filename = _filename.slice(1);
+}
+
+/**
+ * Directory name of the current file.
+ * @type {string}
+ */
+const _dirname = dirname(_filename);
 
 /**
- * Transforms namespace:component to @namespace/template/path
+ * Absolute path to the project root directory.
+ * @type {string}
+ */
+const projectDir = resolve(_dirname, '../../../../..');
+
+/**
+ * Webpack plugin to resolve custom namespace imports.
+ * Transforms `<prefix>:<component>` into `<prefix>/<component>` paths.
  */
 class ProjectNameResolverPlugin {
+  /**
+   * @param {object} options - Plugin options.
+   * @param {string} options.projectName - Prefix for the project namespace.
+   */
   constructor(options = {}) {
     this.prefix = options.projectName;
   }
 
+  /**
+   * Apply the webpack resolver hook.
+   * @param {object} resolver - The webpack resolver instance.
+   */
   apply(resolver) {
     const target = resolver.ensureHook('resolve');
-    resolver
-      .getHook('before-resolve')
-      .tapAsync('ProjectNameResolverPlugin', (request, resolveContext, callback) => {
+    resolver.getHook('before-resolve').tapAsync(
+      'ProjectNameResolverPlugin',
+      /**
+       * @param {object} request - The resolve request object.
+       * @param {object} resolveContext - Context for resolving.
+       * @param {Function} callback - Callback to continue resolution.
+       */
+      (request, resolveContext, callback) => {
         const requestPath = request.request;
 
-        if (requestPath && requestPath.startsWith(`${this.prefix}:`)) {
-          const newRequestPath = requestPath.replace(`${this.prefix}:`, `${this.prefix}/`);
+        if (
+          requestPath &&
+          requestPath.startsWith(`${this.prefix}:`)
+        ) {
+          const newRequestPath = requestPath.replace(
+            `${this.prefix}:`,
+            `${this.prefix}/`
+          );
           const newRequest = {
             ...request,
             request: newRequestPath,
@@ -40,31 +77,53 @@ class ProjectNameResolverPlugin {
         } else {
           callback();
         }
-      });
+      }
+    );
   }
 }
 
-module.exports = async ({ config }) => {
+/**
+ * Export a function to customize the Webpack config for Storybook.
+ * @param {object} param0 - The Storybook configuration object.
+ * @param {object} param0.config - The existing webpack config to modify.
+ * @returns {object} The updated webpack config.
+ */
+export default async function ({ config }) {
   // Alias
   Object.assign(config.resolve.alias, resolves.TwigResolve.alias);
 
-  // Twig
+  // Twig loader
   config.module.rules.push({
+    /**
+     * @type {RegExp}
+     */
     test: /\.twig$/,
     use: [
       {
-        loader: path.resolve(__dirname, '../config/webpack/sdc-loader.js'),
+        /**
+         * Custom loader for svg/spritemap integration.
+         * @type {string}
+         */
+        loader: resolve(_dirname, '../config/webpack/sdc-loader.js'),
         options: {
+          /**
+           * Name of the Emulsify project for resolving.
+           * @type {string}
+           */
           projectName: emulsifyConfig.project.name,
         },
       },
       {
+        /**
+         * Standard Twig JS loader.
+         * @type {string}
+         */
         loader: 'twigjs-loader',
       },
     ],
   });
 
-  // SCSS
+  // SCSS Loader configuration
   config.module.rules.push({
     test: /\.s[ac]ss$/i,
     use: [
@@ -72,6 +131,10 @@ module.exports = async ({ config }) => {
       {
         loader: 'css-loader',
         options: {
+          /**
+           * Enable source maps for CSS.
+           * @type {boolean}
+           */
           sourceMap: true,
         },
       },
@@ -87,38 +150,44 @@ module.exports = async ({ config }) => {
     ],
   });
 
-  // YAML
+  // YAML loader
   config.module.rules.push({
+    /**
+     * @type {RegExp}
+     */
     test: /\.ya?ml$/,
     loader: 'js-yaml-loader',
   });
 
-  // Plugins
+  // StyleLint and ESLint plugins
   config.plugins.push(
     new _StyleLintPlugin({
-      configFile: path.resolve(__dirname, '../', '.stylelintrc.json'),
-      context: path.resolve(__dirname, '../', 'src'),
+      configFile: resolve(projectDir, '../', '.stylelintrc.json'),
+      context: resolve(projectDir, '../', 'src'),
       files: '**/*.scss',
       failOnError: false,
       quiet: false,
     }),
     new ESLintPlugin({
-      context: path.resolve(__dirname, '../', 'src'),
+      context: resolve(projectDir, '../', 'src'),
       extensions: ['js'],
     }),
   );
 
-  // Resolver Plugins
+  // Custom resolver plugin for namespaced imports
   config.resolve.plugins = [
     new ProjectNameResolverPlugin({
       projectName: emulsifyConfig.project.name,
     }),
   ];
 
-  // Configure fallback for optional modules that may not be present
+  // Fallback for optional modules
   config.resolve.fallback = {
+    /**
+     * Prevent resolution of components directory if missing.
+     */
     '../../../../components': false,
   };
 
   return config;
-};
+}

package/commitlint.config.js

@@ -1,3 +1,5 @@
-module.exports = {
-  extends: ['@commitlint/config-conventional'],
+const Configuration = {
+  extends: ["@commitlint/config-conventional"],
 };
+
+export default Configuration;

package/config/babel.config.js

@@ -1,8 +1,7 @@
-module.exports = (api) => {
+export default (api) => {
   api.cache(true);
 
   const presets = [['minify', { builtIns: false }]];
-
   const comments = false;
 
   return { presets, comments };

package/config/eslint.config.js

@@ -0,0 +1,74 @@
+// Import ESLint Flat Config and required plugins
+import js from '@eslint/js';
+import babelParser from '@babel/eslint-parser';
+import importPlugin from 'eslint-plugin-import';
+import pluginSecurity from 'eslint-plugin-security';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+
+export default [
+  // Base ESLint recommended rules
+  js.configs.recommended,
+
+  // Plugin configurations
+  importPlugin.flatConfigs.recommended,
+  pluginSecurity.configs.recommended,
+  eslintPluginPrettierRecommended,
+
+  {
+    name: 'emulsify-core-config',
+    languageOptions: {
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          babelrc: false,
+          configFile: false,
+        },
+      },
+      sourceType: 'module',
+      ecmaVersion: 'latest',
+      globals: {
+        expect: true,
+        it: true,
+        describe: true,
+      },
+    },
+
+    files: ['**/*.{js,mjs,cjs}'],
+
+    ignores: ['**/*.min.js', '**/node_modules/**/*'],
+
+    rules: {
+      strict: 0,
+      'consistent-return': 'off',
+      'no-underscore-dangle': 'off',
+      'max-nested-callbacks': ['warn', 3],
+      'import/extensions': 'off',
+      'import/no-unresolved': 'off',
+      'import/no-extraneous-dependencies': 'warn',
+      'import/no-mutable-exports': 'warn',
+      'no-plusplus': ['warn', { allowForLoopAfterthoughts: true }],
+      'no-param-reassign': 'off',
+      'no-prototype-builtins': 'off',
+      'prettier/prettier': ['error', { singleQuote: true }],
+      'no-unused-vars': 'warn',
+      'no-undef': 'off',
+      'operator-linebreak': [
+        'error',
+        'after',
+        { overrides: { '?': 'ignore', ':': 'ignore' } },
+      ],
+      quotes: ['error', 'single'],
+    },
+
+    settings: {
+      'import/ignore': ['\\.(scss|less|css)$'],
+      'import/resolver': {
+        node: {
+          extensions: ['.js', '.jsx'],
+          moduleDirectory: ['src', 'node_modules'],
+        },
+      },
+    },
+  },
+];

package/config/postcss.config.js

@@ -1,5 +1,5 @@
-const autoPrefixer = require('autoprefixer');
+import autoPrefixer from 'autoprefixer';
 
-module.exports = {
+export default {
   plugins: [autoPrefixer()],
 };

package/config/webpack/loaders.js

@@ -1,6 +1,10 @@
-const MiniCssExtractPlugin = require('mini-css-extract-plugin');
-const globImporter = require('node-sass-glob-importer');
-const fs = require('fs-extra');
+/**
+ * @fileoverview Configures Webpack loaders.
+ */
+
+import MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import globImporter from 'node-sass-glob-importer';
+import fs from 'fs-extra';
 
 let babelConfig;
 let postcssConfig;
@@ -71,14 +75,19 @@ const CSSLoader = {
 };
 
 const SVGSpriteLoader = {
-  test: /icons\/.*\.svg$/, // your icons directory
-  loader: 'svg-sprite-loader',
-  options: {
-    extract: true,
-    runtimeCompat: true,
-    outputPath: 'dist/',
-    spriteFilename: './icons.svg',
-  },
+  test: /icons\/.*\.svg$/,
+  use: [
+    {
+      loader: 'svg-sprite-loader',
+      options: {
+        extract: true,
+        esModule: true,
+        runtimeCompat: true,
+        outputPath: 'dist/',
+        spriteFilename: './icons.svg',
+      },
+    },
+  ],
 };
 
 const TwigLoader = {
@@ -88,7 +97,7 @@ const TwigLoader = {
   },
 };
 
-module.exports = {
+export default {
   JSLoader,
   CSSLoader,
   SVGSpriteLoader,

package/config/webpack/optimizers.js

@@ -1,4 +1,4 @@
-const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');
+import ImageMinimizerPlugin from 'image-minimizer-webpack-plugin';
 
 const ImageMinimizer = new ImageMinimizerPlugin({
   minimizer: {
@@ -13,6 +13,6 @@ const ImageMinimizer = new ImageMinimizerPlugin({
   },
 });
 
-module.exports = {
+export default {
   minimizer: [ImageMinimizer],
 };

package/config/webpack/plugins.js

@@ -1,45 +1,52 @@
-/* eslint-disable no-underscore-dangle */
-const path = require('path');
-const webpack = require('webpack');
-const { CleanWebpackPlugin } = require('clean-webpack-plugin');
-const _MiniCssExtractPlugin = require('mini-css-extract-plugin');
-const _SpriteLoaderPlugin = require('svg-sprite-loader/plugin');
-const CopyPlugin = require('copy-webpack-plugin');
-const glob = require('glob');
-const fs = require('fs-extra');
+/**
+ * @fileoverview Configures Webpack plugins.
+ */
+
+import { resolve, dirname } from 'path';
+import webpack from 'webpack';
+import { CleanWebpackPlugin } from 'clean-webpack-plugin';
+import _MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import _SpriteLoaderPlugin from 'svg-sprite-loader/plugin.js';
+import CopyPlugin from 'copy-webpack-plugin';
+import { sync as globSync } from 'glob';
+import fs from 'fs-extra';
+import emulsifyConfig from '../../../../../project.emulsify.json' with { type: 'json' };
+
+// Create __filename from import.meta.url without fileURLToPath
+let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
 
-// Get directories for file contexts.
-const projectDir = path.resolve(__dirname, '../../../../..');
-const srcDir = path.resolve(projectDir, 'src');
+// On Windows, remove the leading slash (e.g. "/C:/path" -> "C:/path")
+if (process.platform === 'win32' && _filename.startsWith('/')) {
+  _filename = _filename.slice(1);
+}
+
+const _dirname = dirname(_filename);
 
-// Emulsify project configuration.
-const emulsifyConfig = require('../../../../../project.emulsify.json');
+const projectDir = resolve(_dirname, '../../../../..');
+const srcDir = resolve(projectDir, 'src');
 
-// Compress images plugin.
 const MiniCssExtractPlugin = new _MiniCssExtractPlugin({
   filename: '[name].css',
   chunkFilename: '[id].css',
 });
 
-// Create SVG sprite.
 const SpriteLoaderPlugin = new _SpriteLoaderPlugin({
   plainSprite: true,
 });
 
-// Enable Webpack progress plugin.
 const ProgressPlugin = new webpack.ProgressPlugin();
 
-// Glob pattern for markup files.
-const componentFilesPattern = path.resolve(srcDir, '**/*.{twig,component.yml}');
+const componentFilesPattern = resolve(srcDir, '**/*.{twig,component.yml}');
 
 /**
- * Prepare list of twig files to copy to "compiled" directories.
- * @constructor
- * @param {string} filesMatcher - Glob pattern.
+ * Prepare a list of patterns for copying Twig and component files.
+ *
+ * @param {string} filesMatcher - Glob pattern for matching files.
+ * @returns {Array<Object>} Array of objects with `from` and `to` properties.
  */
 function getPatterns(filesMatcher) {
   const patterns = [];
-  glob.sync(filesMatcher).forEach((file) => {
+  globSync(filesMatcher).forEach((file) => {
     const projectPath = file.split('/src/')[0];
     const srcStructure = file.split(`${srcDir}/`)[1];
     const parentDir = srcStructure.split('/')[0];
@@ -57,32 +64,29 @@ function getPatterns(filesMatcher) {
       to: newfilePath,
     });
   });
-
   return patterns;
 }
 
-// Copy twig files from src directory.
-const CopyTwigPlugin = fs.existsSync(path.resolve(projectDir, 'src'))
-  ? new CopyPlugin({
-      patterns: getPatterns(componentFilesPattern),
-    })
+const CopyTwigPlugin = fs.pathExistsSync(resolve(projectDir, 'src'))
+  ? new CopyPlugin({ patterns: getPatterns(componentFilesPattern) })
   : '';
 
-// Export plugin configuration.
-module.exports = {
+const pluginConfig = {
   ProgressPlugin,
   MiniCssExtractPlugin,
   SpriteLoaderPlugin,
   CopyTwigPlugin,
   CleanWebpackPlugin: new CleanWebpackPlugin({
-    protectWebpackAssets: false, // Required for removal of extra, unwanted dist/css/*.js files.
+    protectWebpackAssets: false,
     cleanOnceBeforeBuildPatterns: ['!*.{png,jpg,gif,svg}'],
     cleanAfterEveryBuildPatterns: [
       'remove/**',
       '!js',
-      'css/**/*.js', // Remove all unwanted, auto generated JS files from dist/css folder.
+      'css/**/*.js',
       'css/**/*.js.map',
       '!*.{png,jpg,gif,svg}',
     ],
   }),
 };
+
+export default pluginConfig;

package/config/webpack/resolves.js

@@ -1,37 +1,51 @@
-const path = require('path');
-const glob = require('glob');
-const fs = require('fs-extra');
+/**
+ * @fileoverview Configures Twig alias resolution for the project.
+ */
+
+import { basename, dirname, resolve } from 'path';
+import { sync as globSync } from 'glob';
+import fs from 'fs-extra';
+import emulsifyConfig from '../../../../../project.emulsify.json' with { type: 'json' };
 
-// Emulsify project configuration.
-const emulsifyConfig = require('../../../../../project.emulsify.json');
+// Create __filename from import.meta.url without fileURLToPath
+let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
+
+// On Windows, remove the leading slash (e.g. "/C:/path" -> "C:/path")
+if (process.platform === 'win32' && _filename.startsWith('/')) {
+  _filename = _filename.slice(1);
+}
 
-// Get directories for file contexts.
-const projectDir = path.resolve(__dirname, '../../../../..');
+const _dirname = dirname(_filename);
+
+const projectDir = resolve(_dirname, '../../../../..');
 const projectName = emulsifyConfig.project.name;
-const srcDir = fs.existsSync(path.resolve(projectDir, 'src'))
-  ? path.resolve(projectDir, 'src')
-  : path.resolve(projectDir, 'components');
+const srcDir = fs.pathExistsSync(resolve(projectDir, 'src'))
+  ? resolve(projectDir, 'src')
+  : resolve(projectDir, 'components');
 
-// Glob pattern for twig aliases.
-const aliasPattern = path.resolve(srcDir, '**/!(_*).twig');
+const aliasPattern = resolve(srcDir, '**/!(_*).twig');
 
 /**
- * Return all top-level directories from the projects source directory.
- * @constructor
- * @param {string} source - Path to source directory.
+ * Get all top-level directory names from a source directory.
+ *
+ * @param {string} source - The source directory path.
+ * @returns {string[]} Array of directory names.
  */
 function getDirectories(source) {
+  /* eslint-disable security/detect-non-literal-fs-filename */
   const dirs = fs
-    .readdirSync(source, { withFileTypes: true }) // Read contents of the directory
-    .filter((dirent) => dirent.isDirectory()) // Filter only directories
+    .readdirSync(source, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
     .map((dirent) => dirent.name);
+  /* eslint-enable security/detect-non-literal-fs-filename */
   return dirs;
 }
 
 /**
- * Return clean directory names if numbering is used for sorting.
- * @constructor
- * @param {string} dir - Given directory name.
+ * Remove numbering from a directory name if present.
+ *
+ * @param {string} dir - The original directory name.
+ * @returns {string} The cleaned directory name.
  */
 function cleanDirectoryName(dir) {
   if (/^\d{2}/.test(dir)) {
@@ -41,40 +55,33 @@ function cleanDirectoryName(dir) {
 }
 
 /**
- * Return a list of twig file file paths from the project source directory.
- * @constructor
- * @param {string} aliasMatcher - Glob pattern.
+ * Generate a set of Twig aliases from a glob pattern.
+ *
+ * @param {string} aliasMatcher - The glob pattern to match Twig files.
+ * @returns {Object} An object containing Twig aliases.
  */
 function getAliases(aliasMatcher) {
-  // Create default aliases
   let aliases = {};
-  // Add SDC compatible aliases.
-  glob.sync(aliasMatcher).forEach((file) => {
+  globSync(aliasMatcher).forEach((file) => {
     const filePath = file.split(`${srcDir}/`)[1];
-    const fileName = path.basename(filePath);
-
+    const fileName = basename(filePath);
     if (emulsifyConfig.project.platform === 'drupal') {
       aliases[`${projectName}/${fileName.replace('.twig', '')}`] = file;
     }
   });
-  // Add typical @namespace (path to directory) aliases for twig partials.
   const dirs = getDirectories(srcDir);
   dirs.forEach((dir) => {
     const name = cleanDirectoryName(dir);
     Object.assign(aliases, {
-      [`@${name}`]: `${projectDir}/${path.basename(srcDir)}/${dir}`,
+      [`@${name}`]: `${projectDir}/${basename(srcDir)}/${dir}`,
     });
   });
-
   return aliases;
 }
 
-// Alias twig namespaces.
 const TwigResolve = {
   extensions: ['.twig'],
   alias: getAliases(aliasPattern),
 };
 
-module.exports = {
-  TwigResolve,
-};
+export default { TwigResolve };

package/config/webpack/sdc-loader.js

@@ -1,8 +1,16 @@
-module.exports = function (source) {
+/**
+ * A loader function that replaces occurrences of "projectName:" with "projectName/".
+ *
+ * @param {string} source - The source string to process.
+ * @returns {string} The transformed source.
+ */
+export default function (source) {
   const projectName = this.getOptions().projectName || '';
+  /* eslint-disable security/detect-non-literal-regexp */
   const result = source.replace(
     new RegExp(`${projectName}:`, 'g'),
     `${projectName}/`,
   );
+  /* eslint-enable security/detect-non-literal-regexp */
   return result;
-};
+}