@emulsify/core 3.1.1 → 3.3.0

package/.storybook/main.js

@@ -17,13 +17,13 @@ import configOverrides from '../../../../config/emulsify-core/storybook/main.js'
  * The full path to the current file (ESM compatible).
  * @type {string}
  */
-const __filename = fileURLToPath(import.meta.url);
+const _filename = fileURLToPath(import.meta.url);
 
 /**
  * The directory name of the current module file.
  * @type {string}
  */
-const __dirname  = path.dirname(__filename);
+const _dirname  = path.dirname(_filename);
 
 /**
  * Safely apply any user-provided overrides or fall back to an empty object.
@@ -204,7 +204,7 @@ const config = {
 
     // load external manager-head.html if present
     const externalManagerHeadPath = resolve(
-      __dirname,
+      _dirname,
       '../../../../config/emulsify-core/storybook/manager-head.html'
     );
     let externalManagerHtml = '';
@@ -224,7 +224,7 @@ ${externalManagerHtml}`;
    */
   previewHead: (head) => {
     const externalHeadPath = resolve(
-      __dirname,
+      _dirname,
       '../../../../config/emulsify-core/storybook/preview-head.html'
     );
 

package/config/webpack/loaders.js

@@ -37,6 +37,25 @@ const postcssConfigPath = fs.existsSync(
   ? path.resolve('config/emulsify-core/webpack/postcss.config.cjs')
   : require.resolve('@emulsify/core/config/postcss.config.js');
 
+/**
+ * Resolve the directory of this file (without fileURLToPath).
+ * @type {string}
+ */
+let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
+if (process.platform === 'win32' && _filename.startsWith('/')) {
+  _filename = _filename.slice(1);
+}
+const _dirname = path.dirname(_filename);
+
+/**
+ * Root of the project (three levels up from this file).
+ * @type {string}
+ */
+const projectDir = path.resolve(_dirname, '../../../../..');
+
+/** Absolute path to the folder that contains sprite source icons. */
+const ICONS_DIR = path.resolve(projectDir, 'assets/icons');
+
 /**
  * @type {import('webpack').RuleSetRule}
  * JavaScript loader: transpile with Babel.
@@ -111,22 +130,17 @@ const ImageLoader = {
 
 /**
  * @type {import('webpack').RuleSetRule}
- * SVG sprite loader: collects all /icons/*.svg into one sprite.
+ * General SVG loader for non-sprite SVGs (logos, illustrations, etc.).
+ * IMPORTANT: Excludes `assets/icons/` so `svg-spritemap-webpack-plugin`
+ * can consume those files without being intercepted by this rule.
  */
-const SVGSpriteLoader = {
+const SVGLoader = {
   test: /icons\/.*\.svg$/,
-  use: [
-    {
-      loader: 'svg-sprite-loader',
-      options: {
-        extract: true,
-        esModule: true,
-        runtimeCompat: true,
-        outputPath: 'dist/',
-        spriteFilename: './icons.svg',
-      },
-    },
-  ],
+  type: 'asset/resource',
+  generator: {
+    filename: 'icons.svg',
+  },
+  exclude: [ICONS_DIR],
 };
 
 /**
@@ -148,6 +162,6 @@ export default {
   JSLoader,
   CSSLoader,
   ImageLoader,
-  SVGSpriteLoader,
+  SVGLoader,
   TwigLoader,
 };

package/config/webpack/optimizers.js

@@ -5,7 +5,6 @@ const ImageMinimizer = new ImageMinimizerPlugin({
     implementation: ImageMinimizerPlugin.imageminMinify,
     options: {
       plugins: [
-        ['gifsicle', { interlaced: true }],
         ['jpegtran', { progressive: true }],
         ['optipng', { optimizationLevel: 5 }],
       ],

package/config/webpack/plugins.js

@@ -1,8 +1,9 @@
-import { resolve, dirname } from 'path';
+import { resolve, dirname, relative } from 'path';
 import webpack from 'webpack';
 import { CleanWebpackPlugin } from 'clean-webpack-plugin';
+import RemoveEmptyScriptsPlugin from 'webpack-remove-empty-scripts';
 import MiniCssExtractPlugin from 'mini-css-extract-plugin';
-import SpriteLoaderPlugin from 'svg-sprite-loader/plugin.js';
+import SVGSpritemapPlugin from 'svg-spritemap-webpack-plugin';
 import CopyPlugin from 'copy-webpack-plugin';
 import { sync as globSync } from 'glob';
 import fs from 'fs-extra';
@@ -12,21 +13,21 @@ import emulsifyConfig from '../../../../../project.emulsify.json' with { type: '
  * Resolve the directory of this file (without fileURLToPath).
  * @type {string}
  */
-let __filename = decodeURIComponent(new URL(import.meta.url).pathname);
-if (process.platform === 'win32' && __filename.startsWith('/')) {
-  __filename = __filename.slice(1);
+let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
+if (process.platform === 'win32' && _filename.startsWith('/')) {
+  _filename = _filename.slice(1);
 }
-const __dirname = dirname(__filename);
+const _dirname = dirname(_filename);
 
 /**
- * Root of the project (three levels up from this file).
+ * Project root (five levels up).
  * @type {string}
  */
-const projectDir = resolve(__dirname, '../../../../..');
+const projectDir = resolve(_dirname, '../../../../..');
 
 /**
- * Where your source files live (if you have a `/src` folder).
- * Falls back to `components/` if `src/` does not exist.
+ * Where source files live.
+ * Prefer `<project>/src`; fall back to `<project>/components` (legacy layout).
  * @type {string}
  */
 const srcPath = resolve(projectDir, 'src');
@@ -34,8 +35,8 @@ const isSrcExists = fs.pathExistsSync(srcPath);
 const srcDir = isSrcExists ? srcPath : resolve(projectDir, 'components');
 
 /**
- * Where your built assets should live.
- * Mirrors the `srcDir` logic: prefer `dist/` if you have `src/`, else `components/`.
+ * Where built assets live.
+ * If `src/` exists, use `<project>/dist`; else write into `<project>/components`.
  * @type {string}
  */
 const distPath = isSrcExists
@@ -43,8 +44,32 @@ const distPath = isSrcExists
   : resolve(projectDir, 'components');
 
 /**
- * Glob pattern for all Twig & component files in your source.
- * We copy these through CopyPlugin so your PHP/Drupal theme sees them.
+ * Platform switch (affects component output roots).
+ * @type {boolean}
+ */
+const isDrupal = emulsifyConfig?.project?.platform === 'drupal';
+
+/**
+ * Component source root:
+ *  - with src/: `<project>/src/components`
+ *  - without src/: `<project>/components`
+ * @type {string}
+ */
+const componentsSrcRoot = isSrcExists ? resolve(srcDir, 'components') : srcDir;
+
+/**
+ * Component output root (where compiled component assets go):
+ *  - Drupal + src/: `components/…`
+ *  - Otherwise:     `dist/components/…`
+ * (Relative to `projectDir`; used by CopyPlugins `to:` path.)
+ * @type {string}
+ */
+const componentsOutRoot =
+  isDrupal && isSrcExists ? 'components' : 'dist/components';
+
+/**
+ * Glob pattern for Twig & component meta files. These are copied as-is so
+ * Drupal/WordPress themes can consume them alongside compiled assets.
  * @type {string}
  */
 const componentFilesPattern = resolve(
@@ -53,50 +78,158 @@ const componentFilesPattern = resolve(
 );
 
 /**
- * Turn a globbed source list into copy patterns.
+ * Build CopyPlugin patterns from a glob matcher, preserving source structure.
  *
- * @param {string} filesMatcher Glob pattern.
- * @returns {Array<{from:string,to:string}>}
+ * @param {string} filesMatcher - Glob for files to mirror.
+ * @returns {Array<{from:string,to:string}>} Copy patterns for CopyPlugin.
  */
 function getPatterns(filesMatcher) {
   return globSync(filesMatcher).map((file) => {
-    const projectPath = file.split('/src/')[0];
+    const projectPath = file.split('/src/')[0]; // base path before /src/
     const srcStructure = file.split(`${srcDir}/`)[1];
     const parentDir = srcStructure.split('/')[0];
-    // Consolidate foundation/layout under components for Drupal.
+
+    // Consolidate foundation/layout under "components" for Drupal.
     const consolidateDirs =
       parentDir === 'layout' || parentDir === 'foundation'
         ? '/components/'
         : '/';
+
     const filePath = file.split(/(foundation\/|components\/|layout\/)/)[2];
-    const destDir =
-      emulsifyConfig.project.platform === 'drupal'
-        ? `${projectPath}${consolidateDirs}${parentDir}/${filePath}`
-        : `${projectPath}/dist/${parentDir}/${filePath}`;
-    return { from: file, to: destDir };
+
+    const to = isDrupal
+      ? `${projectPath}${consolidateDirs}${parentDir}/${filePath}`
+      : `${projectPath}/dist/${parentDir}/${filePath}`;
+
+    return { from: file, to };
   });
 }
 
 /**
- * Only include CopyPlugin if we actually have a `src/` folder.
+ * CopyPlugin instance (only when `src/` exists):
+ * copies Twig and component meta files 1:1 into their expected destinations.
  * @type {CopyPlugin|false}
  */
 const CopyTwigPlugin = isSrcExists
   ? new CopyPlugin({ patterns: getPatterns(componentFilesPattern) })
   : false;
 
+/* -------------------------------------------------------------------------- */
+/*                          COMPONENT & GLOBAL ASSETS                          */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Asset allow-list (extensions we consider "static assets" to mirror).
+ * Extend to suit your project (e.g., add `pdf`, `txt`, `xml`, etc.).
+ * NOTE: We purposefully exclude code-like files via the filter below.
+ * @type {RegExp}
+ */
+const ASSET_EXT_RE =
+  /\.(?:png|jpe?g|gif|svg|webp|avif|ico|bmp|heic|heif|mp4|webm|mp3|ogg|wav|aac|woff2?|ttf|otf|eot|json|webmanifest|manifest|pdf)$/i;
+
+/**
+ * Exclude code & tooling files (don’t mirror these).
+ * @type {RegExp}
+ */
+const EXCLUDE_CODE_RE =
+  /\.(?:jsx?|tsx?|mjs|cjs|vue|svelte|scss|sass|less|styl|css|map|twig|php|yml|yaml|md|markdown|story(?:book)?\.[jt]sx?|stories\.[jt]sx?|test\.[jt]sx?)$/i;
+
+/**
+ * Shared filter for CopyPlugin patterns.
+ * Decides whether a file should be copied as a "static asset".
+ *
+ * @param {string} resourcePath - Absolute file path on disk.
+ * @param {string} base - The context directory for the pattern.
+ * @returns {boolean} True if we should copy the file.
+ */
+const assetFilter = (resourcePath, base) => {
+  const rel = relative(base, resourcePath);
+  // Guard: stay inside context
+  if (rel.startsWith('..')) return false;
+  // Exclude typical code/tooling files
+  if (EXCLUDE_CODE_RE.test(rel)) return false;
+  // Include known asset extensions
+  return ASSET_EXT_RE.test(rel);
+};
+
+/**
+ * Copy **all static assets inside components**, regardless of folder labels.
+ *
+ * Examples (all preserved under the component’s output root):
+ *   src/components/accordion/assets/dropdown-icon.svg
+ *   src/components/accordion/images/icons/chevron.svg
+ *   src/components/accordion/icon.svg                 (root-level asset)
+ *
+ * @type {CopyPlugin}
+ */
+const CopyComponentAssetsPlugin = new CopyPlugin({
+  patterns: [
+    {
+      // Start at the components root and evaluate every file
+      from: '**/*',
+      context: componentsSrcRoot,
+      to: resolve(projectDir, componentsOutRoot, '[path][name][ext]'),
+      noErrorOnMissing: true,
+      globOptions: {
+        dot: false,
+        ignore: [
+          '**/.DS_Store',
+          '**/Thumbs.db',
+          '**/node_modules/**',
+          '**/dist/**',
+        ],
+      },
+      // Only copy files that match our asset allow-list and are not code
+      filter: (resourcePath) => assetFilter(resourcePath, componentsSrcRoot),
+    },
+  ],
+});
+
+/**
+ * OPTIONAL: Copy **global (non-component) assets** that live under `src/`
+ * but outside `src/components/` (e.g. layout/site assets).
+ *
+ * Mirrors them under `dist/global/…`.
+ * Disabled when there is no `src/` directory.
+ *
+ * @type {CopyPlugin|false}
+ */
+const CopyGlobalAssetsPlugin = isSrcExists
+  ? new CopyPlugin({
+      patterns: [
+        {
+          from: '!(components|util)/**/*',
+          context: srcDir,
+          to: resolve(projectDir, 'dist', 'global', '[path][name][ext]'),
+          noErrorOnMissing: true,
+          globOptions: {
+            dot: false,
+            ignore: [
+              '**/.DS_Store',
+              '**/Thumbs.db',
+              '**/node_modules/**',
+              '**/dist/**',
+            ],
+          },
+          filter: (resourcePath) => assetFilter(resourcePath, srcDir),
+        },
+      ],
+    })
+  : false;
+
+/* -------------------------------------------------------------------------- */
+/*                                 OTHER PLUGINS                               */
+/* -------------------------------------------------------------------------- */
+
 /**
  * CleanWebpackPlugin configuration.
- * Wipes out everything in `distPath` before a build,
- * except image files (we whitelist common image extensions).
+ * Wipes out compiled CSS/JS in `distPath` before a build; keeps images.
  */
 const CleanPlugin = new CleanWebpackPlugin({
   protectWebpackAssets: false,
   cleanOnceBeforeBuildPatterns: [
-    // wipe all compiled assets
     `${distPath}/**/*.css`,
     `${distPath}/**/*.js`,
-    // but keep any images
     `!${distPath}/**/*.png`,
     `!${distPath}/**/*.jpg`,
     `!${distPath}/**/*.gif`,
@@ -104,33 +237,47 @@ const CleanPlugin = new CleanWebpackPlugin({
   ],
 });
 
+/** Removes empty JS files generated for style-only entries. */
+const RemoveEmptyJS = new RemoveEmptyScriptsPlugin();
+
 /**
- * MiniCssExtractPlugin instance: writes `[name].css` into your dist.
+ * MiniCssExtractPlugin: emit CSS next to the entry key path (no hard-coded dist/).
  */
 const CssExtractPlugin = new MiniCssExtractPlugin({
-  filename: '[name].css',
-  chunkFilename: '[id].css',
+  filename: ({ chunk }) => `${chunk.name}.css`,
+  chunkFilename: ({ chunk }) => `${chunk.name}.css`,
 });
 
 /**
- * svg-sprite-loader plugin: bundles all /icons/*.svg.
+ * Generate a single SVG spritemap at `dist/icons.svg`.
  */
-const SpritePlugin = new SpriteLoaderPlugin({
-  plainSprite: true,
-});
+const SpritePlugin = new SVGSpritemapPlugin(
+  resolve(projectDir, 'assets/icons/**/*.svg'),
+  {
+    output: {
+      filename: 'dist/icons.svg',
+      chunk: { keep: true },
+    },
+    sprite: {
+      prefix: '',
+      generate: { title: false },
+    },
+  },
+);
 
-/**
- * webpack.ProgressPlugin for nice build progress output.
- */
+/** Build progress output. */
 const ProgressPlugin = new webpack.ProgressPlugin();
 
 /**
- * Export all plugins keyed for easy inclusion in your final Webpack config.
+ * Export plugin instances keyed for easy inclusion in your Webpack config.
  */
 export default {
   ProgressPlugin,
   CleanWebpackPlugin: CleanPlugin,
+  RemoveEmptyJS,
   MiniCssExtractPlugin: CssExtractPlugin,
-  SpriteLoaderPlugin: SpritePlugin,
+  SpritePlugin,
   CopyTwigPlugin,
+  CopyComponentAssetsPlugin,
+  CopyGlobalAssetsPlugin,
 };

package/config/webpack/resolves.js

@@ -1,88 +1,154 @@
 /**
  * @fileoverview Configures Twig alias resolution for the project.
+ * - Builds Twig alias map from files under the source directory
+ * - Exposes a Webpack-style `resolve.alias` object for `.twig` files
  */
 
-import { basename, dirname, resolve } from 'path';
+import {
+  basename,
+  resolve,
+  relative,
+  isAbsolute,
+  join,
+  posix as path,
+} from 'node:path';
 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
+/**
+ * Resolve the directory of this file (without fileURLToPath).
+ * @type {string}
+ */
 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);
 }
+const _dirname = path.dirname(_filename);
 
-const _dirname = dirname(_filename);
-
+/** @type {string} Absolute project root (five levels up). */
 const projectDir = resolve(_dirname, '../../../../..');
-const projectName = emulsifyConfig.project.name;
-const srcDir = fs.pathExistsSync(resolve(projectDir, 'src'))
-  ? resolve(projectDir, 'src')
-  : resolve(projectDir, 'components');
 
-if (!fs.pathExistsSync(resolve(srcDir))) {
-  fs.mkdirSync(srcDir, { recursive: true });
+/** @type {string} Project machine name used to prefix Drupal aliases. */
+const projectName = String(emulsifyConfig?.project?.name || '').trim();
+
+/**
+ * Determine the source directory: prefer `<project>/src` if it exists,
+ * otherwise use `<project>/components`. If we choose `components` and it
+ * does not exist, create it safely inside the project.
+ *
+ * @returns {string} Absolute path to the source directory.
+ */
+function resolveOrCreateSrcDir() {
+  const srcPreferred = resolve(projectDir, 'src');
+  if (fs.pathExistsSync(srcPreferred)) return srcPreferred;
+
+  const componentsFallback = resolve(projectDir, 'components');
+  if (!fs.pathExistsSync(componentsFallback)) {
+    ensureDirSafe(componentsFallback, {
+      base: projectDir,
+      allowedBasenames: new Set(['components']),
+    });
+  }
+  return componentsFallback;
+}
+
+/**
+ * Safely create a directory after validating it is a subpath of `base`
+ * and its basename is explicitly allowed. This addresses
+ * `security/detect-non-literal-fs-filename`.
+ *
+ * @param {string} dir - Absolute path to create.
+ * @param {{ base: string, allowedBasenames: Set<string> }} opts - Safety options.
+ * @returns {void}
+ * @throws {Error} If the path is outside `base` or not allowed.
+ */
+function ensureDirSafe(dir, { base, allowedBasenames }) {
+  const rel = relative(base, dir);
+  const name = basename(dir);
+
+  // Block absolute or escaping paths (outside of base)
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Refusing to create directory outside project: "${dir}"`);
+  }
+
+  // Only allow known, expected directory names
+  if (!allowedBasenames.has(name)) {
+    throw new Error(`Refusing to create unexpected directory: "${name}"`);
+  }
+
+  // The argument is validated; create the directory.
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  fs.mkdirSync(dir, { recursive: true });
 }
 
+/** @type {string} Absolute source directory. */
+const srcDir = resolveOrCreateSrcDir();
+
+/** @type {string} Glob pattern for all non-partial Twig files (skip leading underscores). */
 const aliasPattern = resolve(srcDir, '**/!(_*).twig');
 
 /**
- * Get all top-level directory names from a source directory.
+ * Read immediate subdirectories from a source directory.
  *
- * @param {string} source - The source directory path.
- * @returns {string[]} Array of directory names.
+ * @param {string} source - Absolute directory to scan.
+ * @returns {string[]} Array of directory names (basenames only).
  */
 function getDirectories(source) {
   /* eslint-disable security/detect-non-literal-fs-filename */
-  const dirs = fs
-    .readdirSync(source, { withFileTypes: true })
-    .filter((dirent) => dirent.isDirectory())
-    .map((dirent) => dirent.name);
+  const entries = fs.readdirSync(source, { withFileTypes: true });
   /* eslint-enable security/detect-non-literal-fs-filename */
-  return dirs;
+  return entries.filter((d) => d.isDirectory()).map((d) => d.name);
 }
 
 /**
- * Remove numbering from a directory name if present.
+ * Strip a leading two-digit ordering prefix from a directory name
+ * (e.g., "01-components" -> "components").
  *
- * @param {string} dir - The original directory name.
- * @returns {string} The cleaned directory name.
+ * @param {string} dir - Original directory name.
+ * @returns {string} Cleaned directory name.
  */
 function cleanDirectoryName(dir) {
-  if (/^\d{2}/.test(dir)) {
-    return dir.slice(3);
-  }
-  return dir;
+  return /^\d{2}-/.test(dir) ? dir.slice(3) : dir;
 }
 
 /**
- * Generate a set of Twig aliases from a glob pattern.
+ * Build a Twig alias object by:
+ *  - Adding per-file aliases for Drupal (e.g., "mytheme/button")
+ *  - Adding top-level section aliases (e.g., "@components", "@layout")
  *
- * @param {string} aliasMatcher - The glob pattern to match Twig files.
- * @returns {Object} An object containing Twig aliases.
+ * @param {string} twigGlob - Glob pattern to locate Twig files.
+ * @returns {Record<string, string>} Alias map ({ alias: absolutePath }).
  */
-function getAliases(aliasMatcher) {
-  let aliases = {};
-  globSync(aliasMatcher).forEach((file) => {
-    const filePath = file.split(`${srcDir}/`)[1];
-    const fileName = basename(filePath);
-    if (emulsifyConfig.project.platform === 'drupal') {
-      aliases[`${projectName}/${fileName.replace('.twig', '')}`] = file;
+function getAliases(twigGlob) {
+  /** @type {Record<string, string>} */
+  const aliases = {};
+
+  // Per-file aliases for Drupal only: "<projectName>/<filename>"
+  if (emulsifyConfig?.project?.platform === 'drupal' && projectName) {
+    for (const file of globSync(twigGlob)) {
+      const relToSrc = relative(srcDir, file);
+      const fileName = basename(relToSrc).replace(/\.twig$/, '');
+      aliases[`${projectName}/${fileName}`] = file;
     }
-  });
-  const dirs = getDirectories(srcDir);
-  dirs.forEach((dir) => {
+  }
+
+  // Top-level "@section" aliases for easier imports
+  const topDirs = getDirectories(srcDir);
+  for (const dir of topDirs) {
     const name = cleanDirectoryName(dir);
-    Object.assign(aliases, {
-      [`@${name}`]: `${projectDir}/${basename(srcDir)}/${dir}`,
-    });
-  });
+    aliases[`@${name}`] = join(projectDir, basename(srcDir), dir);
+  }
+
   return aliases;
 }
 
+/**
+ * Webpack-style `resolve` config for Twig files.
+ * @typedef {{ extensions: string[], alias: Record<string, string> }} TwigResolveConfig
+ */
+
+/** @type {TwigResolveConfig} */
 const TwigResolve = {
   extensions: ['.twig'],
   alias: getAliases(aliasPattern),