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

.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',

.storybook/main.js

@@ -7,23 +7,24 @@
  * @module .storybook/main
  */
 
-import { resolve } from 'path';
 import fs from 'fs';
-import path from 'path';
+import path, { resolve } from 'path';
 import { fileURLToPath } from 'url';
 import configOverrides from '../../../../config/emulsify-core/storybook/main.js';
+import viteConfig from '../config/vite/vite.config.js';
+import { resolveEnvironment } from '../config/vite/environment.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.
@@ -41,7 +42,7 @@ const config = {
    * @type {string[]}
    */
   stories: [
-    '../../../../(src|components)/**/*.stories.@(js|jsx|ts|tsx)',
+    '../../../../@(src|components)/**/*.stories.@(js|jsx|ts|tsx)',
   ],
 
   /**
@@ -59,28 +60,26 @@ 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',
   ],
 
   /**
    * Core builder configuration for Storybook.
    * @type {{builder: string, disableTelemetry: boolean}}
    */
   core: {
-    builder: 'webpack5',
+    builder: '@storybook/builder-vite',
     disableTelemetry: true,
   },
 
   /**
-   * Framework specification for Storybook (HTML + Webpack5).
+   * Framework specification for Storybook (HTML + Vite).
    * @type {{name: string, options: object}}
    */
   framework: {
-    name: '@storybook/html-webpack5',
+    name: '@storybook/react-vite',
     options: {},
   },
 
@@ -204,7 +203,7 @@ const config = {
 
     // load external manager-head.html if present
     const externalManagerHeadPath = resolve(
-      __dirname,
+      _dirname,
       '../../../../config/emulsify-core/storybook/manager-head.html'
     );
     let externalManagerHtml = '';
@@ -213,8 +212,8 @@ const config = {
     }
 
     return `${head}
-${inlineStyles}
-${externalManagerHtml}`;
+      ${inlineStyles}
+      ${externalManagerHtml}`;
   },
 
   /**
@@ -224,7 +223,7 @@ ${externalManagerHtml}`;
    */
   previewHead: (head) => {
     const externalHeadPath = resolve(
-      __dirname,
+      _dirname,
       '../../../../config/emulsify-core/storybook/preview-head.html'
     );
 
@@ -234,7 +233,97 @@ ${externalManagerHtml}`;
     }
 
     return `${head}
-${externalHtml}`;
+      ${externalHtml}`;
+  },
+
+  // Storybook specific Vite configuration.
+  async viteFinal(config) {
+    const { mergeConfig } = await import('vite');
+    const env = resolveEnvironment();
+    const baseViteConfig =
+      typeof viteConfig === 'function'
+        ? await viteConfig({ command: 'serve', mode: config?.mode || 'development' })
+        : viteConfig;
+    const existingDefine = (config && config.define) || {};
+    const viteDefine = (baseViteConfig && baseViteConfig.define) || {};
+    const allowList = new Set([
+      ...(config?.server?.fs?.allow || []),
+      env.projectDir,
+      path.resolve(env.projectDir, 'src'),
+      path.resolve(env.projectDir, 'components'),
+      path.resolve(env.projectDir, 'dist'),
+    ]);
+    const assetsInclude = Array.from(
+      new Set([...(config.assetsInclude || []), ...(baseViteConfig.assetsInclude || []), '**/*.twig']),
+    );
+    const toRootRel = (abs) => {
+      const rel = path.relative(env.projectDir, abs);
+      const normalized = rel.split(path.sep).join('/');
+      return `/${normalized}`.replace(/\/{2,}/g, '/');
+    };
+    const candidateRoots =
+      env.structureOverrides && Array.isArray(env.structureRoots) && env.structureRoots.length
+        ? env.structureRoots
+        : env.srcDir
+          ? [path.join(env.srcDir, 'components')]
+          : [];
+    const rootRels = candidateRoots.map(toRootRel);
+    const globBases = rootRels.length ? rootRels : ['/src/components', '/components'];
+    const twigGlobImports = `mergeGlobMaps([\n${globBases
+      .map((base) => `  import.meta.glob('${base}/**/*.twig', { eager: true })`)
+      .join(',\n')}\n])`;
+
+    return mergeConfig(config, {
+      ...baseViteConfig,
+      define: {
+        ...viteDefine,
+        ...existingDefine,
+        __EMULSIFY_ENV__: JSON.stringify(env),
+      },
+      server: {
+        ...(baseViteConfig?.server || {}),
+        fs: {
+          allow: Array.from(allowList),
+        },
+      },
+      assetsInclude,
+      plugins: [
+        ...(baseViteConfig?.plugins || []),
+        {
+          name: 'emulsify-inject-twig-globs',
+          enforce: 'pre',
+          transform(code, id) {
+            const cleanId = id.split('?')[0];
+            if (!cleanId.endsWith('/.storybook/polyfills/twig-resolver.js')) return null;
+            const replaced = code.replace(
+              /__EMULSIFY_TWIG_GLOB_IMPORTS__/g,
+              twigGlobImports,
+            );
+            return replaced === code ? null : replaced;
+          },
+        },
+      ],
+      esbuild: {
+        'jsx': 'automatic',
+        loader: 'jsx',
+        include: /.*\.jsx?$/,
+        exclude: [],
+      },
+      optimizeDeps: {
+        include: [
+          'path',
+          'twig',
+          'twig-drupal-filters',
+          'bem-twig-extension',
+          'add-attributes-twig-extension',
+        ],
+        esbuildOptions: {
+          loader: {
+            '.js': 'jsx',
+          },
+        },
+      },
+    })
   },
 
   // Merge in user overrides without modifying original logic

.storybook/manager.js

@@ -1,6 +1,6 @@
 // .storybook/manager.js
 
-import { addons } from '@storybook/manager-api';
+import { addons } from 'storybook/manager-api';
 import emulsifyTheme from './emulsifyTheme';
 
 /**
@@ -42,4 +42,3 @@ import('../../../../config/emulsify-core/storybook/theme')
       theme: emulsifyTheme,
     });
   });
-

.storybook/polyfills/twig-include.js

@@ -0,0 +1,36 @@
+
+import resolveTemplate from './twig-resolver.js';
+
+/**
+ * Twig `include()` polyfill.
+ * Mirrors Drupal behaviour inside Storybook.
+ * @param {string} templateName
+ * @param {Object} [variables]
+ * @param {boolean} [withContext=false]
+ * @return {string}
+ */
+function twigInclude(Twig) {
+  Twig.extendFunction('include', (...args) => {
+    let [templateName, variables = {}, withContext = false] = args;
+    if (typeof withContext !== 'boolean' && variables && typeof variables.with_context !== 'undefined') {
+      withContext = variables.with_context;
+      delete variables.with_context;
+    }
+
+    try {
+      const templateFn = resolveTemplate(templateName);
+      if (!templateFn) return '';
+
+      const finalContext = withContext && typeof this === 'object'
+        ? { ...(this.context || {}), ...variables }
+        : variables;
+
+      return templateFn(finalContext);
+    } catch (err) {
+      console.error(`Twig include() failed for: ${templateName}`, err);
+      return '';
+    }
+  });
+};
+
+export default twigInclude;

.storybook/polyfills/twig-resolver.js

@@ -0,0 +1,129 @@
+import { getProjectMachineName } from '../utils';
+
+const namespace = getProjectMachineName();
+
+/**
+ * Build a dynamic module map of Twig files from all possible component roots.
+ * We rely on __EMULSIFY_ENV__ injected in .storybook/main.js via viteFinal(),
+ * using the same “structure overrides / roots” logic you use in environment.js.
+ */
+const ENV = (typeof __EMULSIFY_ENV__ !== 'undefined' && __EMULSIFY_ENV__) || {};
+
+// Determine candidate roots: prefer structure overrides, otherwise src/components.
+const candidateRoots = Array.isArray(ENV?.structureRoots) && ENV?.structureOverrides && ENV.structureRoots.length
+  ? ENV.structureRoots
+  : (ENV?.srcDir ? [`${ENV.srcDir}/components`] : []);
+
+/**
+ * Convert an absolute path to a Vite project-root-relative path, prefixed with "/".
+ * Keys produced by import.meta.glob() will use these forms.
+ * @param {string} abs
+ * @returns {string}
+ */
+function toRootRel(abs) {
+  if (!abs) return '';
+  const projectDir = ENV?.projectDir || '';
+  if (projectDir && abs.startsWith(projectDir)) {
+    const rel = abs.slice(projectDir.length);
+    return rel.startsWith('/') ? rel : `/${rel}`;
+  }
+  // Fall back to assuming it's already project-root-relative-ish.
+  return abs.startsWith('/') ? abs : `/${abs}`;
+}
+
+// Build globs for each candidate root. We’ll eagerly import all Twig modules.
+const rootRels = candidateRoots.map(toRootRel);
+
+// Vite doesn’t support an array directly in a single import.meta.glob(),
+// so merge multiple glob maps into one.
+function mergeGlobMaps(maps) {
+  return Object.assign({}, ...maps);
+}
+
+// Typical component layouts we want to support:
+// - Nested component folders:   /root/thing/thing.twig
+// - Flat component files:       /root/thing.twig
+// We pre-load everything under each root so resolution is O(1).
+const twigModules = mergeGlobMaps(
+  rootRels.flatMap((base) => [
+    import.meta.glob(`${base}/**/*.twig`, { eager: true }),
+  ])
+);
+
+// Helper: generate likely keys for a given component “part” under every root.
+// We try the canonical “part/part.twig”, then “part.twig”.
+function candidateKeysForPart(part) {
+  const keys = [];
+  for (const base of rootRels) {
+    keys.push(`${base}/${part}/${part}.twig`);
+    keys.push(`${base}/${part}.twig`);
+  }
+  return keys;
+}
+
+/**
+ * Resolve template identifier to compiled Twig function.
+ * Supports: @component.twig, namespace:component, @namespace/component, namespace/component
+ * @param {string} name Template identifier
+ * @returns {Function|undefined} Compiled function or noop
+ */
+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(new RegExp(`^@?${namespace}/`), '').replace(/\.twig$/, '');
+
+    const candidates = candidateKeysForPart(part);
+    for (const key of candidates) {
+      const mod = twigModules[key];
+      if (mod) {
+        return mod.default ?? mod;
+      }
+    }
+
+    // eslint-disable-next-line no-console
+    console.error(`Cannot resolve Twig component for '${name}'. Tried: ${candidates.join(', ')}`);
+  }
+
+  // @icon.twig → icon/icon.twig (fallback to icon.twig)
+  if (name.startsWith('@') && name.endsWith('.twig')) {
+    const part = name.slice(1, -5); // remove leading @ and trailing .twig
+    const candidates = candidateKeysForPart(part);
+    for (const key of candidates) {
+      const mod = twigModules[key];
+      if (mod) {
+        return mod.default ?? mod;
+      }
+    }
+    // eslint-disable-next-line no-console
+    console.error(`Cannot resolve Twig shorthand template '${name}'. Tried: ${candidates.join(', ')}`);
+  }
+
+  // namespace/icon.twig via alias-like usage (without @)
+  if (name.startsWith(`${namespace}/`)) {
+    const part = name.replace(new RegExp(`^${namespace}/`), '').replace(/\.twig$/, '');
+    const candidates = candidateKeysForPart(part);
+    for (const key of candidates) {
+      const mod = twigModules[key];
+      if (mod) {
+        return mod.default ?? mod;
+      }
+    }
+    // eslint-disable-next-line no-console
+    console.error(`Cannot resolve Twig alias template '${name}'. Tried: ${candidates.join(', ')}`);
+  }
+
+  // Final attempt: direct key access if caller passed an exact glob key.
+  const direct = twigModules[name];
+  if (direct) {
+    return direct.default ?? direct;
+  }
+
+  // Vite environment: avoid require() fallback; return a safe noop.
+  // eslint-disable-next-line no-console
+  console.error(`Cannot resolve Twig template '${name}'`);
+  return () => '';
+}
+
+export default resolveTemplate;