@emulsify/core 4.0.4 → 4.1.1

package/.storybook/css-components.js

@@ -6,7 +6,10 @@
  * dist/components so the mirrored component CSS is not loaded twice.
  */
 
+// Load mirrored component output first so Drupal adapter stories match theme roots.
 import.meta.glob('../../../../components/**/*.css', { eager: true });
+
+// Keep shared dist CSS while avoiding duplicate generated component CSS.
 import.meta.glob(
   ['../../../../dist/**/*.css', '!../../../../dist/components/**/*.css'],
   { eager: true },

package/.storybook/css-dist.js

@@ -2,4 +2,5 @@
  * @file Storybook compiled dist CSS side-effect loader.
  */
 
+// Import matching CSS for Vite side effects so CSS HMR stays on the native path.
 import.meta.glob('../../../../dist/**/*.css', { eager: true });

package/.storybook/main-static-assets.js

@@ -0,0 +1,217 @@
+import fs from 'fs';
+import path from 'path';
+
+const projectRoot = process.cwd();
+
+/**
+ * Keeps Storybook static directory config aligned to the consuming project.
+ *
+ * @param {Array<string|{from: string, to: string}>} staticDirs - Static directory entries.
+ * @returns {Array<string|{from: string, to: string}>} Existing static directory entries.
+ */
+function existingStaticDirs(staticDirs) {
+  const seen = new Set();
+  const existing = [];
+
+  for (const staticDir of staticDirs) {
+    const directory =
+      typeof staticDir === 'string' ? staticDir : staticDir.from;
+
+    if (!directory || !fs.existsSync(directory)) continue;
+
+    const key =
+      typeof staticDir === 'string'
+        ? staticDir
+        : `${staticDir.from || ''}\0${staticDir.to || ''}`;
+    if (seen.has(key)) continue;
+
+    seen.add(key);
+    existing.push(staticDir);
+  }
+
+  return existing;
+}
+
+/**
+ * Build static directory mounts for normalized project asset roots.
+ *
+ * @param {object} env - Resolved project paths used by Storybook.
+ * @returns {Array<string|{from: string, to: string}>} Static directory entries.
+ */
+export function buildAssetStaticDirs(env) {
+  const configuredAssetRoots = Array.isArray(env.projectStructure?.assetRoots)
+    ? env.projectStructure.assetRoots
+    : [];
+  const assetRoots = [
+    ...configuredAssetRoots,
+    path.resolve(projectRoot, 'assets'),
+    path.resolve(projectRoot, 'src/assets'),
+  ];
+
+  return existingStaticDirs([
+    ...assetRoots.map((root) => ({
+      from: root,
+      to: '/assets',
+    })),
+    {
+      from: path.resolve(projectRoot, 'dist/assets'),
+      to: '/assets',
+    },
+    {
+      from: path.resolve(projectRoot, 'dist/assets'),
+      to: '/',
+    },
+  ]);
+}
+
+/**
+ * Checks whether a resolved file path stays inside an expected directory.
+ *
+ * @param {string} filePath - Resolved candidate file path.
+ * @param {string} directory - Resolved directory that must contain the file.
+ * @returns {boolean} Whether the file path is inside the directory.
+ */
+function isWithinDirectory(filePath, directory) {
+  // `path.relative()` exposes traversal attempts as `..` or absolute paths.
+  const relativePath = path.relative(directory, filePath);
+  return Boolean(
+    relativePath &&
+    !relativePath.startsWith('..') &&
+    !path.isAbsolute(relativePath),
+  );
+}
+
+/**
+ * Returns a browser content type for generated files served by Storybook.
+ *
+ * @param {string} filePath - Resolved file path being served.
+ * @returns {string} HTTP content type header value.
+ */
+function contentTypeForFile(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  // Keep this map small; unknown generated files can still download as binary.
+  const types = {
+    '.css': 'text/css; charset=utf-8',
+    '.gif': 'image/gif',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml; charset=utf-8',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+  };
+
+  return types[extension] || 'application/octet-stream';
+}
+
+/**
+ * Serves generated dist files that may not exist when `staticDirs` is built.
+ *
+ * Storybook validates static directories during config load, but Emulsify
+ * projects often generate `dist` after Storybook starts. This middleware keeps
+ * those generated asset URLs available without replacing Vite's CSS HMR.
+ *
+ * @param {import('http').IncomingMessage} req - Vite dev server request.
+ * @param {import('http').ServerResponse} res - Vite dev server response.
+ * @param {Function} next - Next middleware callback.
+ * @returns {void}
+ */
+function serveGeneratedDistFile(req, res, next) {
+  const method = req.method || 'GET';
+  if (method !== 'GET' && method !== 'HEAD') {
+    next();
+    return;
+  }
+
+  let pathname = '';
+  try {
+    // Malformed URLs should fall through to Storybook's normal Vite server.
+    pathname = decodeURIComponent(
+      new URL(req.url || '/', 'http://localhost').pathname,
+    );
+  } catch {
+    next();
+    return;
+  }
+
+  // These URL shapes match Emulsify's compiled CSS and sprite references.
+  const routes = [
+    {
+      pathname: '/icons.svg',
+      file: path.resolve(projectRoot, 'dist/assets/icons.svg'),
+    },
+    {
+      prefix: '/assets/',
+      directory: path.resolve(projectRoot, 'dist/assets'),
+    },
+    {
+      prefix: '/dist/',
+      directory: path.resolve(projectRoot, 'dist'),
+    },
+  ];
+  const route = routes.find(({ prefix, pathname: routePathname }) =>
+    routePathname ? pathname === routePathname : pathname.startsWith(prefix),
+  );
+  if (!route) {
+    next();
+    return;
+  }
+
+  const filePath = route.file
+    ? route.file
+    : path.resolve(route.directory, pathname.slice(route.prefix.length));
+  // Resolve from known roots only, then reject traversal before reading.
+  if (route.directory && !isWithinDirectory(filePath, route.directory)) {
+    next();
+    return;
+  }
+
+  try {
+    const stats = fs.statSync(filePath);
+    if (!stats.isFile()) {
+      next();
+      return;
+    }
+    if (path.extname(filePath).toLowerCase() === '.css') {
+      next();
+      return;
+    }
+
+    res.statusCode = 200;
+    res.setHeader('Content-Type', contentTypeForFile(filePath));
+    res.setHeader('Content-Length', stats.size);
+    if (method === 'HEAD') {
+      res.end();
+      return;
+    }
+    res.end(fs.readFileSync(filePath));
+  } catch {
+    next();
+  }
+}
+
+/**
+ * Adds Vite dev-server access to generated dist files.
+ *
+ * CSS itself is still imported through native `import.meta.glob()` calls in the
+ * preview runtime; this plugin only fills the static-file gap for late-created
+ * dist assets.
+ *
+ * @returns {import('vite').Plugin} Vite middleware plugin.
+ */
+export function makeGeneratedDistFilesPlugin() {
+  return {
+    name: 'emulsify-generated-dist-files',
+    configureServer(server) {
+      server.middlewares.use(serveGeneratedDistFile);
+      // Watch generated assets so Vite notices files created after startup.
+      server.watcher.add([
+        path.join(projectRoot, 'dist/**/*.css'),
+        path.join(projectRoot, 'dist/assets/**/*'),
+      ]);
+    },
+  };
+}

package/.storybook/main-vite.js

@@ -0,0 +1,224 @@
+import path from 'path';
+import viteConfig from '../config/vite/vite.config.js';
+import { twigExtensionModuleSpecifiers } from '../config/vite/twig-extensions.js';
+import {
+  mergeReactSingletonOptimizeDeps,
+  mergeReactSingletonResolve,
+} from '../config/vite/utils/react-singleton.js';
+import { makeGeneratedDistFilesPlugin } from './main-static-assets.js';
+
+// Twig glob maps are provided by config/vite/plugins/virtual-twig-globs.js.
+const twigVirtualModuleIds = [
+  'virtual:emulsify-twig-globs',
+  'virtual:emulsify-twig-asset-sources',
+  'virtual:emulsify-twig-extension-installers',
+];
+
+const twigRuntimeOptimizeDepsExclude = [
+  ...twigVirtualModuleIds,
+  '@emulsify/core/storybook/twig/source-function',
+  '@emulsify/core/storybook/twig/source',
+  '@emulsify/core/storybook/twig/resolver',
+];
+
+/**
+ * Vite-generated Storybook chunks should not share `/assets` with project
+ * static files. Storybook copies staticDirs while the preview build runs, so
+ * keeping generated chunks in a separate folder avoids concurrent writers in
+ * `.out/assets`.
+ *
+ * @type {string}
+ */
+const storybookViteAssetsDir = 'storybook-assets';
+
+/**
+ * Merge Storybook and project optimizeDeps excludes with Core Twig runtime IDs.
+ *
+ * Storybook's dependency optimizer runs before normal Vite virtual module
+ * resolution. Core Twig runtime modules import virtual IDs that must stay in
+ * the Vite module graph so Emulsify's virtual plugins can resolve them.
+ *
+ * @param {...string[]} excludeLists - Existing optimizeDeps exclude arrays.
+ * @returns {string[]} Merged exclude list.
+ */
+function mergeTwigRuntimeOptimizeDepsExcludes(...excludeLists) {
+  return Array.from(
+    new Set([
+      ...excludeLists.flatMap((excludeList) =>
+        Array.isArray(excludeList) ? excludeList : [],
+      ),
+      ...twigRuntimeOptimizeDepsExclude,
+    ]),
+  );
+}
+
+/**
+ * Keep Emulsify Twig virtual imports out of Storybook dependency prebundles.
+ *
+ * @returns {import('esbuild').Plugin} Esbuild plugin for optimizeDeps.
+ */
+function makeTwigVirtualModuleOptimizerPlugin() {
+  return {
+    name: 'emulsify-twig-virtual-modules',
+    setup(build) {
+      build.onResolve(
+        { filter: /^virtual:emulsify-twig-(?:globs|asset-sources)$/ },
+        (args) => ({
+          path: args.path,
+          external: true,
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Builds the Storybook Vite config merger.
+ *
+ * @param {object} resolvedStorybookEnv - Resolved project paths used by Storybook.
+ * @returns {Function} Storybook `viteFinal` callback.
+ */
+export function createViteFinal(resolvedStorybookEnv) {
+  return async function viteFinal(config) {
+    const { mergeConfig } = await import('vite');
+    const env = resolvedStorybookEnv;
+    const storybookBuildConfig = config?.build || {};
+
+    // Keep using the `serve` branch of the shared Vite config here. Storybook
+    // has historically consumed that branch, while `mode` still reflects
+    // whether Storybook is running in development or production.
+    const mode = config?.mode || 'development';
+    const baseViteConfig =
+      typeof viteConfig === 'function'
+        ? await viteConfig({ command: 'serve', mode })
+        : viteConfig;
+    const existingDefine = (config && config.define) || {};
+    const viteDefine = (baseViteConfig && baseViteConfig.define) || {};
+
+    // Allow Storybook's dev server to read component sources from the project
+    // root and any structure override paths used by Emulsify consumers.
+    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'),
+      ...(Array.isArray(env.projectStructure?.sourceRoots)
+        ? env.projectStructure.sourceRoots
+        : []),
+      ...(Array.isArray(env.componentRoots) ? env.componentRoots : []),
+      ...(Array.isArray(env.structureRoots) ? env.structureRoots : []),
+      ...(env.namespaceRoots && typeof env.namespaceRoots === 'object'
+        ? Object.values(env.namespaceRoots)
+        : []),
+      ...(Array.isArray(env.projectStructure?.assetRoots)
+        ? env.projectStructure.assetRoots
+        : []),
+    ]);
+
+    // Twig files are loaded through custom resolvers/plugins, so they need to
+    // be treated as importable assets by Storybook's Vite pipeline.
+    const assetsInclude = Array.from(
+      new Set([
+        ...(config.assetsInclude || []),
+        ...(baseViteConfig.assetsInclude || []),
+        '**/*.twig',
+      ]),
+    );
+    const optimizeDepsInclude = mergeReactSingletonOptimizeDeps(
+      baseViteConfig?.optimizeDeps?.include,
+      config?.optimizeDeps?.include,
+      [
+        'twig',
+        '@emulsify/core/extensions/twig',
+        ...twigExtensionModuleSpecifiers(env),
+      ],
+    );
+
+    const mergedConfig = mergeConfig(config, {
+      ...baseViteConfig,
+      resolve: mergeReactSingletonResolve(baseViteConfig, config),
+      define: {
+        // Preserve shared and Storybook-provided constants, then publish the
+        // resolved Emulsify environment to client-side code.
+        ...viteDefine,
+        ...existingDefine,
+        __EMULSIFY_ENV__: JSON.stringify(env),
+        'globalThis.__EMULSIFY_ENV__': JSON.stringify(env),
+      },
+      server: {
+        ...(baseViteConfig?.server || {}),
+        fs: {
+          allow: Array.from(allowList),
+        },
+      },
+      assetsInclude,
+      plugins: [
+        ...(baseViteConfig?.plugins || []),
+        makeGeneratedDistFilesPlugin(),
+      ],
+      esbuild: {
+        // Some downstream code is authored as `.js` files containing JSX, so
+        // keep Storybook's esbuild settings aligned with the shared Vite config.
+        jsx: 'automatic',
+        loader: 'jsx',
+        include: /.*\.jsx?$/,
+        exclude: [],
+      },
+      optimizeDeps: {
+        ...(baseViteConfig?.optimizeDeps || {}),
+        ...(config?.optimizeDeps || {}),
+        include: optimizeDepsInclude,
+        exclude: mergeTwigRuntimeOptimizeDepsExcludes(
+          baseViteConfig?.optimizeDeps?.exclude,
+          config?.optimizeDeps?.exclude,
+        ),
+        esbuildOptions: {
+          ...(baseViteConfig?.optimizeDeps?.esbuildOptions || {}),
+          ...(config?.optimizeDeps?.esbuildOptions || {}),
+          plugins: [
+            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.plugins || []),
+            ...(config?.optimizeDeps?.esbuildOptions?.plugins || []),
+            makeTwigVirtualModuleOptimizerPlugin(),
+          ],
+          loader: {
+            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.loader || {}),
+            ...(config?.optimizeDeps?.esbuildOptions?.loader || {}),
+            // Pre-bundle `.js` dependencies with the JSX loader for packages
+            // that ship JSX without a `.jsx` extension.
+            '.js': 'jsx',
+          },
+        },
+      },
+    });
+
+    return {
+      ...mergedConfig,
+      build: {
+        ...(mergedConfig.build || {}),
+        ...(storybookBuildConfig.outDir
+          ? { outDir: storybookBuildConfig.outDir }
+          : {}),
+        assetsDir: storybookViteAssetsDir,
+        emptyOutDir: false,
+      },
+      resolve: mergeReactSingletonResolve(mergedConfig),
+      optimizeDeps: {
+        ...(mergedConfig.optimizeDeps || {}),
+        include: mergeReactSingletonOptimizeDeps(
+          mergedConfig.optimizeDeps?.include,
+        ),
+        exclude: mergeTwigRuntimeOptimizeDepsExcludes(
+          mergedConfig.optimizeDeps?.exclude,
+        ),
+        esbuildOptions: {
+          ...(mergedConfig.optimizeDeps?.esbuildOptions || {}),
+          loader: {
+            ...(mergedConfig.optimizeDeps?.esbuildOptions?.loader || {}),
+            '.js': 'jsx',
+          },
+        },
+      },
+    };
+  };
+}