@emulsify/core 3.4.1 → 3.5.0

package/.storybook/_drupal.js

@@ -32,14 +32,14 @@ window.Drupal = { behaviors: {} };
   Drupal.attachBehaviors = function (context, settings) {
     context = context || document;
     settings = settings || drupalSettings;
-    /** @type {Object.<string, {attach: Function}>} */
-    const behaviors = Drupal.behaviors;
+    /** @type {Array<{attach?: Function}>} */
+    const behaviors = Object.values(Drupal.behaviors);
 
     // Iterate through each behavior and invoke its attach method if defined.
-    Object.keys(behaviors).forEach(function (i) {
-      if (typeof behaviors[i].attach === 'function') {
+    behaviors.forEach(function (behavior) {
+      if (typeof behavior.attach === 'function') {
         try {
-          behaviors[i].attach(context, settings);
+          behavior.attach(context, settings);
         } catch (e) {
           Drupal.throwError(e);
         }

package/.storybook/emulsifyTheme.js

@@ -1,5 +1,5 @@
 // Documentation on theming Storybook: https://storybook.js.org/docs/configurations/theming/
-import { create } from '@storybook/theming';
+import { create } from 'storybook/theming';
 
 export default create({
   base: 'dark',

package/.storybook/main.js

@@ -11,7 +11,10 @@ import { resolve } from 'path';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import configOverrides from '../../../../config/emulsify-core/storybook/main.js';
+import { createRequire } from 'module';
+import extendWebpackConfig from './webpack.config.js';
+
+const require = createRequire(import.meta.url);
 
 /**
  * The full path to the current file (ESM compatible).
@@ -23,26 +26,70 @@ 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);
+
+/**
+ * Migrate the consumer Storybook theme import from "@storybook/theming" to
+ * "storybook/theming" when needed.
+ *
+ * This runs opportunistically during startup and never throws so Storybook
+ * startup is resilient across all projects.
+ */
+const migrateConsumerThemeImport = () => {
+  try {
+    const themeConfigPath = resolve(
+      _dirname,
+      '../../../../config/emulsify-core/storybook/theme.js',
+    );
+
+    if (!fs.existsSync(themeConfigPath)) {
+      return;
+    }
+
+    const originalThemeConfig = fs.readFileSync(themeConfigPath, 'utf8');
+
+    if (!originalThemeConfig.includes('@storybook/theming')) {
+      return;
+    }
+
+    const migratedThemeConfig = originalThemeConfig.replace(
+      /(['"])@storybook\/theming\1/g,
+      '$1storybook/theming$1',
+    );
+
+    if (migratedThemeConfig !== originalThemeConfig) {
+      fs.writeFileSync(themeConfigPath, migratedThemeConfig, 'utf8');
+    }
+  } catch {
+    // Ignore migration failures so Storybook startup is never blocked.
+  }
+};
+
+migrateConsumerThemeImport();
 
 /**
  * Safely apply any user-provided overrides or fall back to an empty object.
  * @type {object}
  */
-const safeConfigOverrides = configOverrides || {};
+const safeConfigOverrides = (() => {
+  try {
+    const overridesModule = require('../../../../config/emulsify-core/storybook/main.js');
+    return overridesModule.default || overridesModule || {};
+  } catch {
+    return {};
+  }
+})();
 
 /**
  * Primary Storybook configuration object.
- * @type {import('@storybook/core-common').StorybookConfig}
+ * @type {import('storybook/internal/types').StorybookConfig}
  */
 const config = {
   /**
    * Patterns for locating story files under src or components directories.
    * @type {string[]}
    */
-  stories: [
-    '../../../../(src|components)/**/*.stories.@(js|jsx|ts|tsx)',
-  ],
+  stories: ['../../../../@(src|components)/**/*.stories.@(js|jsx|ts|tsx)'],
 
   /**
    * Directories to serve as static assets in the Storybook build.
@@ -52,6 +99,7 @@ const config = {
     '../../../../assets/images',
     '../../../../assets/icons',
     '../../../../dist',
+    '../../../../assets/videos',
   ],
 
   /**
@@ -59,28 +107,31 @@ const config = {
    * @type {string[]}
    */
   addons: [
-    '../../../@storybook/addon-a11y',
-    '../../../@storybook/addon-links',
-    '../../../@storybook/addon-essentials',
-    '../../../@storybook/addon-themes',
-    '../../../@storybook/addon-styling-webpack',
+    '@storybook/addon-a11y',
+    '@storybook/addon-links',
+    '@storybook/addon-themes',
+    '@storybook/addon-styling-webpack',
   ],
 
   /**
    * Core builder configuration for Storybook.
-   * @type {{builder: string, disableTelemetry: boolean}}
+   * Storybook 9 splits the HTML renderer from the webpack builder, so the
+   * builder must be declared explicitly instead of relying on html-webpack5.
+   * @type {{builder: {name: string}, disableTelemetry: boolean}}
    */
   core: {
-    builder: 'webpack5',
+    builder: {
+      name: '@storybook/builder-webpack5',
+    },
     disableTelemetry: true,
   },
 
   /**
-   * Framework specification for Storybook (HTML + Webpack5).
+   * Framework specification for Storybook's HTML renderer.
    * @type {{name: string, options: object}}
    */
   framework: {
-    name: '@storybook/html-webpack5',
+    name: '@storybook/server-webpack5',
     options: {},
   },
 
@@ -205,7 +256,7 @@ const config = {
     // load external manager-head.html if present
     const externalManagerHeadPath = resolve(
       _dirname,
-      '../../../../config/emulsify-core/storybook/manager-head.html'
+      '../../../../config/emulsify-core/storybook/manager-head.html',
     );
     let externalManagerHtml = '';
     if (fs.existsSync(externalManagerHeadPath)) {
@@ -225,7 +276,7 @@ ${externalManagerHtml}`;
   previewHead: (head) => {
     const externalHeadPath = resolve(
       _dirname,
-      '../../../../config/emulsify-core/storybook/preview-head.html'
+      '../../../../config/emulsify-core/storybook/preview-head.html',
     );
 
     let externalHtml = '';
@@ -237,6 +288,16 @@ ${externalManagerHtml}`;
 ${externalHtml}`;
   },
 
+  /**
+   * Forward Storybook 9's webpack hook to the existing shared webpack helper so
+   * custom Twig, Sass, YAML, and resolver behavior still applies.
+   * @param {object} storybookConfig - Storybook's generated webpack config.
+   * @param {object} options - Storybook webpack hook options.
+   * @returns {Promise<object>} The merged webpack config.
+   */
+  webpackFinal: async (storybookConfig, options) =>
+    extendWebpackConfig({ config: storybookConfig, ...options }),
+
   // Merge in user overrides without modifying original logic
   ...safeConfigOverrides,
 };

package/.storybook/manager.js

@@ -1,7 +1,7 @@
 // .storybook/manager.js
 
-import { addons } from '@storybook/manager-api';
-import emulsifyTheme from './emulsifyTheme';
+import { addons } from 'storybook/manager-api';
+import emulsifyTheme from './emulsifyTheme.js';
 
 /**
  * Dynamically import the user-provided Storybook theme override.
@@ -19,7 +19,8 @@ import('../../../../config/emulsify-core/storybook/theme')
      */
     const isEmptyObject =
       !customTheme ||
-      (typeof customTheme === 'object' && Object.keys(customTheme).length === 0);
+      (typeof customTheme === 'object' &&
+        Object.keys(customTheme).length === 0);
 
     /**
      * Apply the chosen theme to Storybook’s manager UI configuration.
@@ -42,4 +43,3 @@ import('../../../../config/emulsify-core/storybook/theme')
       theme: emulsifyTheme,
     });
   });
-  

package/.storybook/polyfills/twig-include.js

@@ -1,4 +1,3 @@
-
 import resolveTemplate from './twig-resolver.js';
 
 /**
@@ -12,7 +11,11 @@ import resolveTemplate from './twig-resolver.js';
 function twigInclude(Twig) {
   Twig.extendFunction('include', (...args) => {
     let [templateName, variables = {}, withContext = false] = args;
-    if (typeof withContext !== 'boolean' && variables && typeof variables.with_context !== 'undefined') {
+    if (
+      typeof withContext !== 'boolean' &&
+      variables &&
+      typeof variables.with_context !== 'undefined'
+    ) {
       withContext = variables.with_context;
       delete variables.with_context;
     }
@@ -21,9 +24,10 @@ function twigInclude(Twig) {
       const templateFn = resolveTemplate(templateName);
       if (!templateFn) return '';
 
-      const finalContext = withContext && typeof this === 'object'
-        ? { ...(this.context || {}), ...variables }
-        : variables;
+      const finalContext =
+        withContext && typeof this === 'object'
+          ? { ...(this.context || {}), ...variables }
+          : variables;
 
       return templateFn(finalContext);
     } catch (err) {
@@ -31,6 +35,6 @@ function twigInclude(Twig) {
       return '';
     }
   });
-};
+}
 
 export default twigInclude;

package/.storybook/polyfills/twig-resolver.js

@@ -1,11 +1,11 @@
-import { getProjectMachineName } from '../utils';
+import { getProjectMachineName } from '../utils.js';
 
 const namespace = getProjectMachineName();
 
 const twigComponents = require.context(
   '../../../../../src/components/',
   true,
-  /\.twig$/
+  /\.twig$/,
 );
 
 /**
@@ -17,15 +17,14 @@ const twigComponents = require.context(
 function resolveTemplate(name) {
   // namespace:icon, @namespace/icon.twig
   if (name.startsWith(`${namespace}:`) || name.startsWith(`@${namespace}/`)) {
-    const part = name.startsWith(`${namespace}:`) ? name.split(':')[1] : name.replace(`${namespace}/`, '').replace('.twig', '');
+    const part = name.startsWith(`${namespace}:`)
+      ? name.split(':')[1]
+      : name.replace(`${namespace}/`, '').replace('.twig', '');
     const path = `./${part}/${part}.twig`;
     try {
-      {
-        const mod = twigComponents(path);
-        return mod && mod.default ? mod.default : mod;
-      }
-    } catch (e) {
-      // eslint-disable-next-line no-console
+      const mod = twigComponents(path);
+      return mod && mod.default ? mod.default : mod;
+    } catch {
       console.error(`Cannot resolve Twig component for '${name}' at '${path}'`);
     }
   }
@@ -36,33 +35,36 @@ function resolveTemplate(name) {
     const path = `./${part}/${part}.twig`;
     try {
       return twigComponents(path).default || twigComponents(path);
-    } catch (e) {
-      console.error(`Cannot resolve Twig shorthand template '${name}' at '${path}'`);
+    } catch {
+      console.error(
+        `Cannot resolve Twig shorthand template '${name}' at '${path}'`,
+      );
     }
   }
 
   // namespace/icon.twig via webpack alias
   if (name.startsWith(`${namespace}/`)) {
-    const part = name.replace(new RegExp(`^${namespace}/`), '').replace('.twig', '');
+    const part = name.slice(namespace.length + 1).replace('.twig', '');
     const path = `./${part}/${part}.twig`;
     try {
       return twigComponents(path).default || twigComponents(path);
-    } catch (e) {
-      console.error(`Cannot resolve Twig alias template '${name}' at '${path}'`);
+    } catch {
+      console.error(
+        `Cannot resolve Twig alias template '${name}' at '${path}'`,
+      );
     }
   }
 
   try {
-    {
-      // eslint-disable-next-line import/no-dynamic-require, global-require
-      const mod = require(name);
-      return mod && mod.default ? mod.default : mod;
-    }
-  } catch (e) {
-    // eslint-disable-next-line no-console
-    console.error(`Cannot resolve Twig template '${name}'`, e);
+    // Storybook resolves runtime Twig requests through webpack, so this
+    // fallback intentionally loads a module path determined at render time.
+    // eslint-disable-next-line security/detect-non-literal-require
+    const mod = require(name);
+    return mod && mod.default ? mod.default : mod;
+  } catch (error) {
+    console.error(`Cannot resolve Twig template '${name}'`, error);
     return () => '';
   }
-};
+}
 
 export default resolveTemplate;

package/.storybook/polyfills/twig-source.js

@@ -1,14 +1,27 @@
-import { getProjectMachineName } from '../utils';
+import { getProjectMachineName } from '../utils.js';
 
 const namespace = getProjectMachineName();
 
 // Constants used by the `source()` polyfill.
-const PUBLIC_ASSET_BASE = (typeof window !== 'undefined' && window.location && window.location.hostname && window.location.hostname.endsWith('github.io'))
-  ? `/${namespace}/assets/`
-  : '/assets/';
+const PUBLIC_ASSET_BASE =
+  typeof window !== 'undefined' &&
+  window.location &&
+  window.location.hostname &&
+  window.location.hostname.endsWith('github.io')
+    ? `/${namespace}/assets/`
+    : '/assets/';
 
-const INLINE_ASSET_EXTS = new Set(['svg', 'html', 'twig', 'css', 'js', 'json', 'txt', 'md']);
-const IMAGE_ASSET_EXTS  = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']);
+const INLINE_ASSET_EXTS = new Set([
+  'svg',
+  'html',
+  'twig',
+  'css',
+  'js',
+  'json',
+  'txt',
+  'md',
+]);
+const IMAGE_ASSET_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']);
 
 /**
  * Twig `source()` polyfill.
@@ -33,10 +46,8 @@ function twigSource(Twig) {
         if (xhr.status >= 200 && xhr.status < 300) {
           return xhr.responseText;
         }
-        // eslint-disable-next-line no-console
         console.error(`source(): ${xhr.status} while fetching ${relPath}`);
       } catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`source(): failed to fetch ${relPath}`, err);
       }
     }
@@ -49,6 +60,6 @@ function twigSource(Twig) {
     // Fallback: return public URL.
     return `${PUBLIC_ASSET_BASE}${relPath}`;
   });
-};
+}
 
 export default twigSource;

package/.storybook/preview.js

@@ -1,5 +1,5 @@
 // .storybook/preview.js
-import { useEffect } from '@storybook/preview-api';
+import { useEffect } from 'storybook/preview-api';
 import Twig from 'twig';
 import { setupTwig, fetchCSSFiles } from './utils.js';
 import { getRules } from 'axe-core';
@@ -8,7 +8,7 @@ import { getRules } from 'axe-core';
  * External override parameters loaded from project config file, if present.
  * @type {object}
  */
-let externalOverrides = {};
+let externalOverrides;
 
 // Load the preview.js from the project config overrides.
 try {
@@ -16,10 +16,9 @@ try {
    * Dynamically require external preview overrides.
    * @module '../../../../config/emulsify-core/storybook/preview.js'
    */
-  externalOverrides = require(
-    '../../../../config/emulsify-core/storybook/preview.js'
-  ).default;
-} catch (err) {
+  externalOverrides =
+    require('../../../../config/emulsify-core/storybook/preview.js').default;
+} catch {
   // no override file? swallow the error and use {}
   externalOverrides = {};
 }
@@ -34,10 +33,10 @@ import './_drupal.js';
  */
 function enableRulesByTag(tags = []) {
   const allRules = getRules();
-  return allRules.map(rule =>
-    tags.some(t => rule.tags.includes(t))
+  return allRules.map((rule) =>
+    tags.some((t) => rule.tags.includes(t))
       ? { id: rule.ruleId, enabled: true }
-      : { id: rule.ruleId, enabled: false }
+      : { id: rule.ruleId, enabled: false },
   );
 }
 
@@ -54,13 +53,81 @@ const AxeRules = enableRulesByTag([
   'best-practice',
 ]);
 
+/**
+ * Cache of rendered story output keyed by story id.
+ * Storybook server renderer calls `storyFn()` before `fetchStoryHtml`, so
+ * decorators can stash markup here and fetch can read it without re-rendering.
+ *
+ * @type {Map<string, unknown>}
+ */
+const renderedStoryCache = new Map();
+
+/**
+ * Converts a rendered story return value into an HTML string.
+ *
+ * @param {unknown} rendered
+ *   The rendered story result.
+ *
+ * @returns {string}
+ *   Normalized HTML string.
+ */
+function toHtmlString(rendered) {
+  if (typeof rendered === 'string') {
+    return rendered;
+  }
+
+  if (rendered && typeof rendered === 'object') {
+    if (typeof rendered.outerHTML === 'string') {
+      return rendered.outerHTML;
+    }
+    if (typeof rendered.html === 'string') {
+      return rendered.html;
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Default server renderer adapter for Storybook 9 server-webpack5.
+ * Falls back to local story functions so projects do not need a remote
+ * `parameters.server.url` endpoint for basic HTML/Twig stories.
+ *
+ * @param {string} _url
+ *   Unused URL from server parameters.
+ * @param {string} _path
+ *   Unused story path/id from server parameters.
+ * @param {object} _params
+ *   Unused merged server params.
+ * @param {object} storyContext
+ *   Story context from Storybook.
+ *
+ * @returns {Promise<string>}
+ *   Story markup as an HTML string.
+ */
+async function fetchStoryHtmlFromStoryContext(
+  _url,
+  _path,
+  _params,
+  storyContext,
+) {
+  const storyId = storyContext?.id || _path;
+  if (!storyId || !renderedStoryCache.has(storyId)) {
+    return '';
+  }
+
+  const rendered = await Promise.resolve(renderedStoryCache.get(storyId));
+  return toHtmlString(rendered);
+}
+
 // Initialize Twig and load any CSS that your stories need.
 setupTwig(Twig);
 fetchCSSFiles();
 
 /**
  * Storybook decorators to apply Drupal behaviors before rendering each story.
- * @type {Array<import('@storybook/react').Decorator>}
+ * The HTML renderer still uses the generic Storybook decorator signature.
+ * @type {Function[]}
  */
 export const decorators = [
   /**
@@ -69,11 +136,17 @@ export const decorators = [
    * @param {object} context Story context including args.
    * @returns {Function} Rendered story.
    */
-  (Story, { args }) => {
+  (Story, context) => {
+    const { args, id } = context;
     useEffect(() => {
       Drupal.attachBehaviors();
     }, [args]);
-    return Story();
+
+    const rendered = Story();
+    if (id) {
+      renderedStoryCache.set(id, rendered);
+    }
+    return rendered;
   },
 ];
 
@@ -91,6 +164,11 @@ const defaultParams = {
     },
   },
   layout: 'fullscreen',
+  server: {
+    url: '',
+    fetchStoryHtml: fetchStoryHtmlFromStoryContext,
+    params: {},
+  },
 };
 
 /**

package/.storybook/utils.js

@@ -3,8 +3,8 @@ import twigDrupal from 'twig-drupal-filters';
 import twigBEM from 'bem-twig-extension';
 import twigAddAttributes from 'add-attributes-twig-extension';
 import emulsifyConfig from '../../../../project.emulsify.json' with { type: 'json' };
-import twigInclude from './polyfills/twig-include';
-import twigSource from './polyfills/twig-source';
+import twigInclude from './polyfills/twig-include.js';
+import twigSource from './polyfills/twig-source.js';
 
 // Create __filename from import.meta.url without fileURLToPath
 let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
@@ -25,7 +25,7 @@ const _dirname = dirname(_filename);
 const fetchVariantConfig = () => {
   try {
     return emulsifyConfig.variant.structureImplementations;
-  } catch (e) {
+  } catch {
     return [
       {
         name: 'components',
@@ -49,10 +49,14 @@ const fetchCSSFiles = () => {
 
     // Load all CSS files from 'components' for 'drupal' platform.
     if (emulsifyConfig.project.platform === 'drupal') {
-      const drupalCSSFiles = require.context('../../../../components', true, /\.css$/);
+      const drupalCSSFiles = require.context(
+        '../../../../components',
+        true,
+        /\.css$/,
+      );
       drupalCSSFiles.keys().forEach((file) => drupalCSSFiles(file));
     }
-  } catch (e) {
+  } catch {
     return undefined;
   }
 };
@@ -66,16 +70,18 @@ const fetchCSSFiles = () => {
 export function getProjectMachineName() {
   try {
     return emulsifyConfig.project.machineName;
-  } catch (e) {
+  } catch {
     return undefined;
   }
-};
+}
 
 // Build namespaces mapping.
-export const namespaces = {};
-for (const { name, directory } of fetchVariantConfig()) {
-  namespaces[name] = resolve(_dirname, '../../../../', directory);
-}
+export const namespaces = Object.fromEntries(
+  fetchVariantConfig().map(({ name, directory }) => [
+    name,
+    resolve(_dirname, '../../../../', directory),
+  ]),
+);
 
 /**
  * Configures and extends a standard Twig object.

package/.storybook/webpack.config.js

@@ -1,10 +1,13 @@
 import { dirname, resolve } from 'path';
+import { createRequire } from 'module';
 import globImporter from 'node-sass-glob-importer';
 import _StyleLintPlugin from 'stylelint-webpack-plugin';
-import ESLintPlugin from 'eslint-webpack-plugin';
+import webpack from 'webpack';
 import resolves from '../config/webpack/resolves.js';
 import emulsifyConfig from '../../../../project.emulsify.json' with { type: 'json' };
 
+const require = createRequire(import.meta.url);
+
 // Create __filename from import.meta.url without fileURLToPath
 let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
 
@@ -54,13 +57,10 @@ class ProjectNameResolverPlugin {
       (request, resolveContext, callback) => {
         const requestPath = request.request;
 
-        if (
-          requestPath &&
-          requestPath.startsWith(`${this.prefix}:`)
-        ) {
+        if (requestPath && requestPath.startsWith(`${this.prefix}:`)) {
           const newRequestPath = requestPath.replace(
             `${this.prefix}:`,
-            `${this.prefix}/`
+            `${this.prefix}/`,
           );
           const newRequest = {
             ...request,
@@ -70,14 +70,14 @@ class ProjectNameResolverPlugin {
           resolver.doResolve(
             target,
             newRequest,
-            `Resolved ${this.prefix} URI: ${resolves.TwigResolve.alias[requestPath]}`,
+            `Resolved ${this.prefix} URI`,
             resolveContext,
-            callback
+            callback,
           );
         } else {
           callback();
         }
-      }
+      },
     );
   }
 }
@@ -89,77 +89,138 @@ class ProjectNameResolverPlugin {
  * @returns {object} The updated webpack config.
  */
 export default async function ({ config }) {
+  config.resolve = config.resolve || {};
+  config.plugins = config.plugins || [];
+
+  config.module = config.module || {};
+  config.module.rules = config.module.rules || [];
+
+  const hasLoader = (rule, loaderName) => {
+    if (!rule) {
+      return false;
+    }
+
+    if (typeof rule.loader === 'string' && rule.loader.includes(loaderName)) {
+      return true;
+    }
+
+    const use = rule.use;
+    if (typeof use === 'string') {
+      return use.includes(loaderName);
+    }
+    if (Array.isArray(use)) {
+      return use.some((entry) => {
+        if (typeof entry === 'string') {
+          return entry.includes(loaderName);
+        }
+        return (
+          entry &&
+          typeof entry.loader === 'string' &&
+          entry.loader.includes(loaderName)
+        );
+      });
+    }
+
+    return false;
+  };
+
+  const hasRule = (testRegex, loaderName) =>
+    config.module.rules.some(
+      (rule) =>
+        rule &&
+        rule.test &&
+        String(rule.test) === String(testRegex) &&
+        hasLoader(rule, loaderName),
+    );
+
+  const pushRuleOnce = (rule, loaderName) => {
+    if (!hasRule(rule.test, loaderName)) {
+      config.module.rules.push(rule);
+    }
+  };
+
   // Alias
   Object.assign(config.resolve.alias, resolves.TwigResolve.alias);
 
   // Twig loader
-  config.module.rules.push({
-    /**
-     * @type {RegExp}
-     */
-    test: /\.twig$/,
-    use: [
-      {
-        /**
-         * Custom loader for svg/spritemap integration.
-         * @type {string}
-         */
-        loader: resolve(_dirname, '../config/webpack/sdc-loader.js'),
-        options: {
+  pushRuleOnce(
+    {
+      /**
+       * @type {RegExp}
+       */
+      test: /\.twig$/,
+      use: [
+        {
           /**
-           * Name of the Emulsify project for resolving.
+           * Custom loader for svg/spritemap integration.
            * @type {string}
            */
-          projectName: emulsifyConfig.project.name,
+          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 Loader configuration
-  config.module.rules.push({
-    test: /\.s[ac]ss$/i,
-    use: [
-      'style-loader',
-      {
-        loader: 'css-loader',
-        options: {
+        {
           /**
-           * Enable source maps for CSS.
-           * @type {boolean}
+           * Standard Twig JS loader.
+           * @type {string}
            */
-          sourceMap: true,
+          loader: 'twigjs-loader',
         },
-      },
-      {
-        loader: 'sass-loader',
-        options: {
-          sourceMap: true,
-          sassOptions: {
-            importer: globImporter(),
+      ],
+    },
+    'twigjs-loader',
+  );
+
+  // SCSS Loader configuration
+  pushRuleOnce(
+    {
+      test: /\.s[ac]ss$/i,
+      use: [
+        'style-loader',
+        {
+          loader: 'css-loader',
+          options: {
+            /**
+             * Enable source maps for CSS.
+             * @type {boolean}
+             */
+            sourceMap: true,
           },
         },
-      },
-    ],
-  });
+        {
+          loader: 'sass-loader',
+          options: {
+            sourceMap: true,
+            sassOptions: {
+              importer: globImporter(),
+            },
+          },
+        },
+      ],
+    },
+    'sass-loader',
+  );
 
   // YAML loader
-  config.module.rules.push({
-    /**
-     * @type {RegExp}
-     */
-    test: /\.ya?ml$/,
-    loader: 'js-yaml-loader',
-  });
+  pushRuleOnce(
+    {
+      /**
+       * @type {RegExp}
+       */
+      test: /\.ya?ml$/,
+      loader: 'js-yaml-loader',
+    },
+    'js-yaml-loader',
+  );
 
-  // StyleLint and ESLint plugins
+  // Keep style linting in the Storybook webpack build. ESLint runs via the
+  // dedicated npm scripts instead, which avoids coupling Storybook to a
+  // specific ESLint major version.
   config.plugins.push(
     new _StyleLintPlugin({
       configFile: resolve(projectDir, '../', '.stylelintrc.json'),
@@ -168,10 +229,6 @@ export default async function ({ config }) {
       failOnError: false,
       quiet: false,
     }),
-    new ESLintPlugin({
-      context: resolve(projectDir, '../', 'src'),
-      extensions: ['js'],
-    }),
   );
 
   // Custom resolver plugin for namespaced imports
@@ -181,13 +238,32 @@ export default async function ({ config }) {
     }),
   ];
 
-  // Fallback for optional modules
+  // Merge fallbacks so we do not clobber Storybook defaults.
   config.resolve.fallback = {
+    ...(config.resolve.fallback || {}),
+    process: require.resolve('process/browser'),
     /**
      * Prevent resolution of components directory if missing.
      */
     '../../../../components': false,
   };
 
+  // Provide global `process` for browser bundles that pull in node-style libs.
+  const hasProcessProvidePlugin = config.plugins.some(
+    (plugin) =>
+      plugin &&
+      plugin.constructor &&
+      plugin.constructor.name === 'ProvidePlugin' &&
+      plugin.definitions &&
+      Object.prototype.hasOwnProperty.call(plugin.definitions, 'process'),
+  );
+  if (!hasProcessProvidePlugin) {
+    config.plugins.push(
+      new webpack.ProvidePlugin({
+        process: 'process/browser',
+      }),
+    );
+  }
+
   return config;
 }

package/config/babel.config.js

@@ -1,7 +1,17 @@
 export default (api) => {
   api.cache(true);
 
-  const presets = [['minify', { builtIns: false }]];
+  const presets = [
+    [
+      'minify',
+      {
+        builtIns: false,
+        mangle: {
+          reserved: ['Drupal', 'drupalSettings', 'once'],
+        },
+      },
+    ],
+  ];
   const comments = false;
 
   return { presets, comments };

package/config/eslint.config.js

@@ -1,7 +1,5 @@
 // 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';
 
@@ -10,21 +8,12 @@ export default [
   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: {
@@ -43,10 +32,6 @@ export default [
       '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',
@@ -60,15 +45,5 @@ export default [
       ],
       quotes: ['error', 'single'],
     },
-
-    settings: {
-      'import/ignore': ['\\.(scss|less|css)$'],
-      'import/resolver': {
-        node: {
-          extensions: ['.js', '.jsx'],
-          moduleDirectory: ['src', 'node_modules'],
-        },
-      },
-    },
   },
 ];

package/config/webpack/optimizers.js

@@ -1,4 +1,5 @@
 import ImageMinimizerPlugin from 'image-minimizer-webpack-plugin';
+import TerserPlugin from 'terser-webpack-plugin';
 
 const ImageMinimizer = new ImageMinimizerPlugin({
   minimizer: {
@@ -12,6 +13,14 @@ const ImageMinimizer = new ImageMinimizerPlugin({
   },
 });
 
+const TerserMinimizer = new TerserPlugin({
+  terserOptions: {
+    mangle: {
+      reserved: ['Drupal', 'drupalSettings', 'once'],
+    },
+  },
+});
+
 export default {
-  minimizer: [ImageMinimizer],
+  minimizer: [ImageMinimizer, TerserMinimizer],
 };

package/config/webpack/webpack.common.js

@@ -232,6 +232,10 @@ const buildEntries = () => {
 export default {
   target: 'web',
   stats: { errorDetails: true },
+  externals: {
+    drupal: 'Drupal',
+    drupalSettings: 'drupalSettings',
+  },
   entry: buildEntries(),
   module: {
     rules: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Bundled tooling for Storybook development + Webpack Build",
   "keywords": [
     "component library",
@@ -37,35 +37,29 @@
     "husky:pre-commit": "npm run lint",
     "lint": "npm run lint-js",
     "lint-fix": "npm run lint-js -- --fix",
-    "lint-js": "eslint --config config/eslint.config.js --no-error-on-unmatched-pattern ./config ./storybook",
+    "lint-js": "eslint --config config/eslint.config.js --no-error-on-unmatched-pattern ./config ./.storybook",
     "lint-staged": "lint-staged",
     "prepare": "[ -d '.git' ] && (husky install) || true",
     "prettier": "prettier --config config/prettierrc.json --ignore-unknown \"**/*.{js,yml,scss,md}\"",
     "prettier-fix": "prettier --config config/prettierrc.json --write --ignore-unknown \"**/*.{js,yml,scss,md}\"",
     "semantic-release": "semantic-release --config ./release.config.cjs",
-    "storybook": "NODE_OPTIONS=--no-deprecation storybook dev --ci -s ../../dist,../../assets/images,../../assets/icons,../../assets/videos -p 6006",
-    "storybook-build": "storybook build -s ../../dist,../../assets/images,../../assets/icons,../../assets/videos -o .out",
+    "storybook": "NODE_OPTIONS=--no-deprecation storybook dev --ci -p 6006",
+    "storybook-build": "storybook build -o .out",
     "storybook-deploy": "storybook-to-ghpages -o .out",
     "test": "jest --coverage  --config ./config/jest.config.js",
     "twatch": "jest --no-coverage --watch --verbose"
   },
   "dependencies": {
     "@babel/core": "^7.28.5",
-    "@babel/eslint-parser": "^7.28.5",
     "@babel/preset-env": "^7.28.5",
     "@emulsify/cli": "^1.11.4",
-    "@eslint/js": "^9.38.0",
-    "@storybook/addon-a11y": "^8.6.14",
-    "@storybook/addon-actions": "^8.6.14",
-    "@storybook/addon-essentials": "^8.6.14",
-    "@storybook/addon-links": "^8.6.14",
-    "@storybook/addon-styling-webpack": "^1.0.1",
-    "@storybook/addon-themes": "^8.6.14",
-    "@storybook/html": "^8.6.14",
-    "@storybook/html-webpack5": "^8.6.14",
-    "@storybook/manager-api": "^8.6.14",
-    "@storybook/preview-api": "^8.6.14",
-    "@storybook/theming": "^8.6.14",
+    "@eslint/js": "^10.0.1",
+    "@storybook/addon-a11y": "^9.1.20",
+    "@storybook/addon-links": "^9.1.20",
+    "@storybook/addon-styling-webpack": "^2.0.0",
+    "@storybook/addon-themes": "^9.1.20",
+    "@storybook/builder-webpack5": "^9.1.20",
+    "@storybook/server-webpack5": "^9.1.20",
     "add-attributes-twig-extension": "^0.1.0",
     "autoprefixer": "^10.4.21",
     "babel-loader": "^10.0.0",
@@ -74,22 +68,19 @@
     "breakpoint-sass": "^3.0.0",
     "clean-webpack-plugin": "^4.0.0",
     "concurrently": "^9.2.1",
-    "copy-webpack-plugin": "^13.0.1",
+    "copy-webpack-plugin": "^14.0.0",
     "css-loader": "^7.1.1",
-    "eslint": "^9.38.0",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jest": "^29.0.1",
+    "eslint-plugin-jest": "^29.15.1",
     "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-security": "^3.0.1",
-    "eslint-plugin-storybook": "^0.12.0",
-    "eslint-webpack-plugin": "^5.0.2",
+    "eslint-plugin-security": "^4.0.0",
     "file-loader": "^6.2.0",
     "fs-extra": "^11.3.2",
-    "glob": "^11.0.3",
+    "glob": "^13.0.6",
     "graceful-fs": "^4.2.11",
     "html-webpack-plugin": "^5.6.4",
-    "image-minimizer-webpack-plugin": "^4.1.4",
+    "image-minimizer-webpack-plugin": "^5.0.0",
     "imagemin": "^9.0.1",
     "imagemin-jpegtran": "^8.0.0",
     "imagemin-optipng": "^8.0.0",
@@ -100,7 +91,7 @@
     "mini-css-extract-plugin": "^2.9.4",
     "node-sass-glob-importer": "^5.3.3",
     "normalize.css": "^8.0.1",
-    "open-cli": "^8.0.0",
+    "open-cli": "^9.0.0",
     "pa11y": "^9.0.1",
     "postcss": "^8.5.6",
     "postcss-loader": "^8.2.0",
@@ -109,20 +100,20 @@
     "regenerator-runtime": "^0.14.1",
     "sass": "^1.93.2",
     "sass-loader": "^16.0.6",
-    "storybook": "^8.6.14",
+    "storybook": "^9.1.20",
     "style-dictionary": "^5.1.1",
-    "stylelint": "^16.25.0",
-    "stylelint-config-standard-scss": "^16.0.0",
+    "stylelint": "^17.7.0",
+    "stylelint-config-standard-scss": "^17.0.0",
     "stylelint-prettier": "^5.0.3",
-    "stylelint-selector-bem-pattern": "^4.0.1",
     "stylelint-webpack-plugin": "^5.0.1",
     "svg-spritemap-webpack-plugin": "^5.0.3",
+    "terser-webpack-plugin": "^5.3.9",
     "token-transformer": "^0.0.33",
     "twig-drupal-filters": "^3.2.0",
     "twig-testing-library": "^1.2.0",
     "twigjs-loader": "^1.0.3",
     "webpack": "^5.102.1",
-    "webpack-cli": "^6.0.1",
+    "webpack-cli": "^7.0.2",
     "webpack-merge": "^6.0.1",
     "webpack-remove-empty-scripts": "^1.1.1",
     "yaml": "^2.8.1"
@@ -133,17 +124,17 @@
     "@semantic-release/changelog": "^6.0.2",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/github": "^12.0.6",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "all-contributors-cli": "^6.26.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.6",
-    "semantic-release": "^24.2.9"
+    "semantic-release": "^25.0.3"
   },
   "overrides": {
     "inflight": "^1.0.7",
     "graceful-fs": "^4.2.11",
-    "glob": "^11.0.3",
+    "glob": "^13.0.6",
     "rimraf": "^4.3.0",
     "source-map-url": "^0.4.1",
     "source-map-resolve": "^0.6.0",

package/release.config.cjs

@@ -24,7 +24,7 @@ module.exports = {
         }
       }
     ],
-    ['@semantic-release/npm', { npmPublish: false }],
+    ['@semantic-release/npm', { npmPublish: true }],
     '@semantic-release/github'
   ]
 }