@emulsify/core 3.5.0 → 4.0.0

package/.storybook/main.js

@@ -1,20 +1,62 @@
-// .storybook/main.js
-
 /**
- * Storybook main configuration file.
- * This configures stories, static directories, addons, core builder,
- * framework, documentation settings, manager head styles, and overrides.
+ * Central Storybook configuration for Emulsify.
+ *
+ * This shared config defines the default Storybook behavior for consumers of
+ * the package, then lets a project layer local overrides on top at the end.
+ * The main custom behavior here is:
+ * - injecting manager/preview head markup
+ * - adapting the shared Vite config for Storybook
+ * - wiring Twig template discovery into the Storybook build
+ *
  * @module .storybook/main
  */
 
-import { resolve } from 'path';
 import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { createRequire } from 'module';
-import extendWebpackConfig from './webpack.config.js';
+import path, { resolve } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import viteConfig from '../config/vite/vite.config.js';
+import { resolveEnvironment } from '../config/vite/environment.js';
+import {
+  mergeReactSingletonOptimizeDeps,
+  mergeReactSingletonResolve,
+} from '../config/vite/utils/react-singleton.js';
+import { twigExtensionModuleSpecifiers } from '../config/vite/twig-extensions.js';
+import {
+  applyStorybookConfigOverrides,
+  normalizeStorybookConfigOverrideModule,
+} from '../src/storybook/main-config.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',
+];
+
+/**
+ * Minimal subset of the resolved Emulsify environment used by this file.
+ *
+ * @typedef {object} StorybookEnvironment
+ * @property {string} projectDir - Absolute path to the consuming project root.
+ * @property {boolean} [structureOverrides] - Whether custom structure roots are enabled.
+ * @property {string[]} [structureRoots] - Absolute component root paths when overrides are active.
+ * @property {string[]} [componentRoots] - Absolute component roots in resolution order.
+ * @property {Record<string, string>} [namespaceRoots] - Twig namespace roots.
+ * @property {string} [srcDir] - Absolute path to the project's `src` directory when present.
+ */
 
-const require = createRequire(import.meta.url);
+/**
+ * Storybook config type used for editor hints in this plain JS file.
+ * @typedef {import('@storybook/core-common').StorybookConfig} StorybookConfig
+ */
 
 /**
  * The full path to the current file (ESM compatible).
@@ -29,114 +71,227 @@ const _filename = fileURLToPath(import.meta.url);
 const _dirname = path.dirname(_filename);
 
 /**
- * Migrate the consumer Storybook theme import from "@storybook/theming" to
- * "storybook/theming" when needed.
+ * Reads an optional HTML fragment relative to this config file.
  *
- * This runs opportunistically during startup and never throws so Storybook
- * startup is resilient across all projects.
+ * Missing files are treated as empty content so downstream projects can opt in
+ * to extra markup without making Storybook fail on startup.
+ *
+ * @param {string} relativePath - Relative path from this file to the HTML fragment.
+ * @returns {string} File contents when the fragment exists, otherwise an empty string.
  */
-const migrateConsumerThemeImport = () => {
-  try {
-    const themeConfigPath = resolve(
-      _dirname,
-      '../../../../config/emulsify-core/storybook/theme.js',
-    );
+function readOptionalHtmlFragment(relativePath) {
+  const fragmentPath = resolve(_dirname, relativePath);
+
+  if (!fs.existsSync(fragmentPath)) {
+    return '';
+  }
 
-    if (!fs.existsSync(themeConfigPath)) {
-      return;
-    }
+  return fs.readFileSync(fragmentPath, 'utf8');
+}
 
-    const originalThemeConfig = fs.readFileSync(themeConfigPath, 'utf8');
+/**
+ * Keeps Storybook static directory config aligned to the consuming project.
+ *
+ * Storybook errors when a declared static directory is absent, so only expose
+ * project asset directories that exist in the current workspace.
+ *
+ * @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) {
+  return staticDirs.filter((staticDir) => {
+    const directory =
+      typeof staticDir === 'string' ? staticDir : staticDir.from;
 
-    if (!originalThemeConfig.includes('@storybook/theming')) {
-      return;
-    }
+    return directory && fs.existsSync(directory);
+  });
+}
 
-    const migratedThemeConfig = originalThemeConfig.replace(
-      /(['"])@storybook\/theming\1/g,
-      '$1storybook/theming$1',
-    );
+/**
+ * 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,
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Reads optional project-level Storybook overrides.
+ *
+ * Downstream projects can provide this file, but the shared config also needs
+ * to load in package-level smoke tests where that project file is absent.
+ *
+ * @returns {Promise<{ config: object|Function, extendConfig?: Function, replaceAddons: boolean }>}
+ * Consumer overrides.
+ */
+async function loadConfigOverrides() {
+  const overridePath = resolve(
+    _dirname,
+    '../../../../config/emulsify-core/storybook/main.js',
+  );
 
-    if (migratedThemeConfig !== originalThemeConfig) {
-      fs.writeFileSync(themeConfigPath, migratedThemeConfig, 'utf8');
-    }
-  } catch {
-    // Ignore migration failures so Storybook startup is never blocked.
+  if (!fs.existsSync(overridePath)) {
+    return normalizeStorybookConfigOverrideModule();
+  }
+
+  const configOverrides = await import(pathToFileURL(overridePath).href);
+  return normalizeStorybookConfigOverrideModule(configOverrides);
+}
+
+/**
+ * Builds Storybook story globs from normalized project roots.
+ *
+ * Stories remain colocated with components, whether the project uses the
+ * recommended `src/components` layout, legacy root `components`, or explicit
+ * structure implementation directories.
+ *
+ * @param {StorybookEnvironment} env - Resolved project paths used by Storybook.
+ * @returns {string[]} Storybook story globs.
+ */
+function buildStoryGlobs(env) {
+  if (Array.isArray(env.projectStructure?.storyRoots)) {
+    return env.projectStructure.storyRoots.map((root) =>
+      path
+        .resolve(root, '**/*.stories.@(js|jsx|ts|tsx)')
+        .split(path.sep)
+        .join('/'),
+    );
   }
-};
 
-migrateConsumerThemeImport();
+  const roots =
+    env.structureOverrides &&
+    Array.isArray(env.structureRoots) &&
+    env.structureRoots.length
+      ? env.structureRoots
+      : [
+          path.resolve(env.projectDir, 'src'),
+          path.resolve(env.projectDir, 'components'),
+        ];
+
+  return Array.from(new Set(roots.filter(Boolean))).map((root) =>
+    path
+      .resolve(root, '**/*.stories.@(js|jsx|ts|tsx)')
+      .split(path.sep)
+      .join('/'),
+  );
+}
 
 /**
  * Safely apply any user-provided overrides or fall back to an empty object.
  * @type {object}
  */
-const safeConfigOverrides = (() => {
-  try {
-    const overridesModule = require('../../../../config/emulsify-core/storybook/main.js');
-    return overridesModule.default || overridesModule || {};
-  } catch {
-    return {};
-  }
-})();
+const safeConfigOverrides = await loadConfigOverrides();
+
+/**
+ * Environment details shared across this Storybook config load.
+ * @type {StorybookEnvironment}
+ */
+const resolvedStorybookEnv = resolveEnvironment();
 
 /**
  * Primary Storybook configuration object.
- * @type {import('storybook/internal/types').StorybookConfig}
+ * @type {StorybookConfig}
  */
-const config = {
+const baseConfig = {
   /**
-   * Patterns for locating story files under src or components directories.
+   * Discover stories from both supported component roots.
+   *
+   * This shared config supports projects that keep stories under `src` as well
+   * as projects that expose a top-level `components` directory.
+   *
    * @type {string[]}
    */
-  stories: ['../../../../@(src|components)/**/*.stories.@(js|jsx|ts|tsx)'],
+  stories: buildStoryGlobs(resolvedStorybookEnv),
 
   /**
-   * Directories to serve as static assets in the Storybook build.
-   * @type {string[]}
+   * Mount shared assets into Storybook's static file server.
+   *
+   * Anything referenced by URL inside stories should live in one of these
+   * directories so it works in both `storybook dev` and static builds.
+   *
+   * @type {Array<string|{from: string, to: string}>}
    */
   staticDirs: [
-    '../../../../assets/images',
-    '../../../../assets/icons',
-    '../../../../dist',
-    '../../../../assets/videos',
+    ...existingStaticDirs([
+      {
+        from: path.resolve(process.cwd(), 'assets'),
+        to: '/assets',
+      },
+      path.resolve(process.cwd(), 'dist'),
+    ]),
   ],
 
   /**
-   * List of Storybook addons to enable various features.
+   * Enable the default addon set used by Emulsify.
+   *
+   * `a11y` adds accessibility tooling, `links` supports story-to-story
+   * navigation, and `themes` exposes theme switching in the Storybook UI.
+   *
    * @type {string[]}
    */
   addons: [
     '@storybook/addon-a11y',
     '@storybook/addon-links',
     '@storybook/addon-themes',
-    '@storybook/addon-styling-webpack',
   ],
 
   /**
-   * Core builder configuration for Storybook.
-   * 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}}
+   * Force the Vite builder and disable Storybook telemetry for shared usage.
+   * @type {{builder: string, disableTelemetry: boolean}}
    */
   core: {
-    builder: {
-      name: '@storybook/builder-webpack5',
-    },
+    builder: '@storybook/builder-vite',
     disableTelemetry: true,
   },
 
   /**
-   * Framework specification for Storybook's HTML renderer.
+   * Tell Storybook to use the React + Vite framework package.
    * @type {{name: string, options: object}}
    */
   framework: {
-    name: '@storybook/server-webpack5',
+    name: '@storybook/react-vite',
     options: {},
   },
 
   /**
-   * Documentation settings for Storybook autodocs.
+   * Disable automatic docs generation.
+   *
+   * Storybook will only render documentation pages that are authored
+   * explicitly instead of generating them from component metadata.
+   *
    * @type {{autodocs: boolean}}
    */
   docs: {
@@ -144,13 +299,17 @@ const config = {
   },
 
   /**
-   * Custom styles injected into the Storybook manager (sidebar) head,
-   * plus any external manager-head.html snippet.
-   * @param {string} head - Existing head HTML.
-   * @returns {string} Modified head HTML.
+   * Appends Emulsify branding to the Storybook manager UI.
+   *
+   * This only affects Storybook's chrome, such as the sidebar, toolbar, and
+   * addon panels. It does not affect the iframe where stories actually render.
+   *
+   * @param {string} head - Existing manager head markup provided by Storybook.
+   * @returns {string} Manager head markup with Emulsify additions appended.
    */
   managerHead: (head) => {
-    // inline theme styles
+    // Keep the manager styling inline so consumers inherit the branded UI
+    // without having to maintain a separate manager-only stylesheet.
     const inlineStyles = `
       <style>
       :root {
@@ -167,7 +326,7 @@ const config = {
         --colors-purple: #8B1E7E;
       }
       .sidebar-container {
-        background: url('https://raw.githubusercontent.com/fourkitchens/emulsify-core/main/assets/images/corner-bkg.png?token=GHSAT0AAAAAACIEXLVDMX56QK3ZIZWHWHTEZNYFYIA') no-repeat top left;
+        background-color: var(--colors-emulsify-blue-900);
       }
       .sidebar-container .sidebar-subheading {
         color: var(--colors-emulsify-blue-200);
@@ -177,7 +336,7 @@ const config = {
       .sidebar-container .sidebar-subheading button:focus {
         color: var(--colors-emulsify-blue-300);
       }
-      /** Triangle icon **/
+      /* Triangle icon. */
       .sidebar-container .sidebar-subheading button span {
         color: var(--colors-emulsify-blue-300);
       }
@@ -252,54 +411,186 @@ const config = {
       }
     </style>
     `;
-
-    // load external manager-head.html if present
-    const externalManagerHeadPath = resolve(
-      _dirname,
+    const externalManagerHtml = readOptionalHtmlFragment(
       '../../../../config/emulsify-core/storybook/manager-head.html',
     );
-    let externalManagerHtml = '';
-    if (fs.existsSync(externalManagerHeadPath)) {
-      externalManagerHtml = fs.readFileSync(externalManagerHeadPath, 'utf8');
-    }
 
     return `${head}
-${inlineStyles}
-${externalManagerHtml}`;
+      ${inlineStyles}
+      ${externalManagerHtml}`;
   },
 
   /**
-   * Function to load and append an external preview-head.html into the preview iframe.
-   * @param {string} head - Existing preview head HTML.
-   * @returns {string} Combined head HTML including external snippet if present.
+   * Appends project-level head markup to the story preview iframe.
+   *
+   * This is the place for preview-only fonts, scripts, or meta tags that the
+   * rendered component output depends on.
+   *
+   * @param {string} head - Existing preview head markup provided by Storybook.
+   * @returns {string} Preview head markup with optional project HTML appended.
    */
   previewHead: (head) => {
-    const externalHeadPath = resolve(
-      _dirname,
+    const externalHtml = readOptionalHtmlFragment(
       '../../../../config/emulsify-core/storybook/preview-head.html',
     );
 
-    let externalHtml = '';
-    if (fs.existsSync(externalHeadPath)) {
-      externalHtml = fs.readFileSync(externalHeadPath, 'utf8');
-    }
-
     return `${head}
-${externalHtml}`;
+      ${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.
+   * Merges Storybook's generated Vite config with Emulsify's shared Vite config.
+   *
+   * Storybook supplies a baseline config, but Emulsify still needs to expose
+   * the resolved environment, expand filesystem access, and expose the Twig
+   * virtual glob module used by the runtime resolver.
+   *
+   * @param {import('vite').UserConfig} config - Storybook's generated Vite config.
+   * @returns {Promise<import('vite').UserConfig>} Final Vite config used by Storybook.
    */
-  webpackFinal: async (storybookConfig, options) =>
-    extendWebpackConfig({ config: storybookConfig, ...options }),
+  async viteFinal(config) {
+    const { mergeConfig } = await import('vite');
+    /** @type {StorybookEnvironment} */
+    const env = resolvedStorybookEnv;
+
+    // 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),
+      ],
+    );
 
-  // Merge in user overrides without modifying original logic
-  ...safeConfigOverrides,
+    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 || [])],
+      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,
+      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',
+          },
+        },
+      },
+    };
+  },
 };
 
+/**
+ * Primary Storybook configuration after project overrides have been applied.
+ * Project `addons` append to Emulsify defaults unless replacement is requested.
+ *
+ * @type {StorybookConfig}
+ */
+const config = await applyStorybookConfigOverrides(
+  baseConfig,
+  safeConfigOverrides,
+  { env: resolvedStorybookEnv },
+);
+
 export default config;

package/.storybook/manager.js

@@ -1,7 +1,9 @@
-// .storybook/manager.js
+/**
+ * @file Storybook manager bootstrap and theme selection.
+ */
 
 import { addons } from 'storybook/manager-api';
-import emulsifyTheme from './emulsifyTheme.js';
+import emulsifyTheme from './emulsifyTheme';
 
 /**
  * Dynamically import the user-provided Storybook theme override.
@@ -9,37 +11,28 @@ import emulsifyTheme from './emulsifyTheme.js';
  */
 import('../../../../config/emulsify-core/storybook/theme')
   /**
-   * Handle successful dynamic import of the theme module.
+   * Apply a project theme override when one exists.
+   *
    * @param {{ default: object }} module - The imported theme module.
    */
   .then(({ default: customTheme }) => {
-    /**
-     * Determine if the imported theme object is empty or not.
-     * @type {boolean}
-     */
+    // Empty override files should still fall back to the package theme.
     const isEmptyObject =
       !customTheme ||
       (typeof customTheme === 'object' &&
         Object.keys(customTheme).length === 0);
 
-    /**
-     * Apply the chosen theme to Storybook’s manager UI configuration.
-     * @type {{ theme: object }}
-     */
     addons.setConfig({
       theme: isEmptyObject ? emulsifyTheme : customTheme,
     });
   })
   /**
-   * Handle failure of the dynamic import (e.g., file not found).
+   * Fall back to the default theme when the project override is absent.
+   *
    * @returns {void}
    */
   .catch(() => {
     addons.setConfig({
-      /**
-       * Fallback to the default Emulsify theme on import error.
-       * @type {{ theme: object }}
-       */
       theme: emulsifyTheme,
     });
   });