@emulsify/core 3.5.0 → 4.0.1

package/config/vite/utils/react-singleton.js

@@ -0,0 +1,85 @@
+/**
+ * @file React singleton helpers for Storybook and Vite config.
+ */
+
+import { unique } from './unique.js';
+
+/**
+ * React modules that must resolve from the consumer project root.
+ *
+ * @type {string[]}
+ */
+export const reactSingletonModules = [
+  'react',
+  'react-dom',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+];
+
+const asArray = (value) => (Array.isArray(value) ? value : []);
+
+const isObjectAlias = (alias) =>
+  alias && typeof alias === 'object' && !Array.isArray(alias);
+
+/**
+ * Merge Vite alias config when all aliases use object syntax.
+ *
+ * Array-style aliases are already order-sensitive Vite config, so this helper
+ * leaves mixed/array alias forms to Vite's normal merge behavior.
+ *
+ * @param {...import('vite').UserConfig} configs - Vite config objects.
+ * @returns {object|undefined} Merged alias object when applicable.
+ */
+function mergeObjectAliases(...configs) {
+  const aliases = configs
+    .map((config) => config?.resolve?.alias)
+    .filter(Boolean);
+
+  if (!aliases.length || aliases.some((alias) => !isObjectAlias(alias))) {
+    return undefined;
+  }
+
+  return Object.assign({}, ...aliases);
+}
+
+/**
+ * Merge Vite resolve config while forcing React to a single project instance.
+ *
+ * Later configs override earlier shallow resolve properties, while all dedupe
+ * lists are preserved and extended with React's runtime modules.
+ *
+ * @param {...import('vite').UserConfig} configs - Vite config objects.
+ * @returns {import('vite').UserConfig['resolve']} Merged resolve config.
+ */
+export function mergeReactSingletonResolve(...configs) {
+  const alias = mergeObjectAliases(...configs);
+  const mergedResolve = configs.reduce(
+    (merged, config) => ({
+      ...merged,
+      ...(config?.resolve || {}),
+    }),
+    {},
+  );
+
+  return {
+    ...mergedResolve,
+    ...(alias ? { alias } : {}),
+    dedupe: unique([
+      ...configs.flatMap((config) => asArray(config?.resolve?.dedupe)),
+      ...reactSingletonModules,
+    ]),
+  };
+}
+
+/**
+ * Merge optimizeDeps include lists and include React singleton modules.
+ *
+ * @param {...string[]} includeLists - Existing optimizeDeps include arrays.
+ * @returns {string[]} Merged include list.
+ */
+export function mergeReactSingletonOptimizeDeps(...includeLists) {
+  return unique([
+    ...includeLists.flatMap((includeList) => asArray(includeList)),
+    ...reactSingletonModules,
+  ]);
+}

package/config/vite/utils/unique.js

@@ -0,0 +1,36 @@
+/**
+ * @file Shared array de-duplication helpers.
+ */
+
+/**
+ * Return values in first-seen order with duplicates removed.
+ *
+ * @template T
+ * @param {T[]} values - Values to deduplicate.
+ * @returns {T[]} Unique values.
+ */
+export function unique(values = []) {
+  return Array.from(new Set(values));
+}
+
+/**
+ * Return values in first-seen order with duplicates removed by key.
+ *
+ * @template T
+ * @param {T[]} values - Values to deduplicate.
+ * @param {(value: T) => *} keyFn - Function that returns a comparable key.
+ * @returns {T[]} Unique values.
+ */
+export function uniqueBy(values = [], keyFn) {
+  const seen = new Set();
+  const result = [];
+
+  for (const value of values) {
+    const key = keyFn(value);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(value);
+  }
+
+  return result;
+}

package/config/vite/vite.config.js

@@ -0,0 +1,161 @@
+/**
+ * @file Vite configuration for Emulsify.
+ * @see https://vite.dev/config/
+ *
+ * @overview
+ * This configuration wires Emulsify's Vite build in a few clear steps:
+ *
+ *  1. Resolve the build environment (paths, platform flags) via {@link resolveEnvironment}.
+ *  2. Build the Rollup/Vite entries map with {@link buildInputs}.
+ *  3. Load optional project extensions (extra plugins and/or a config patcher)
+ *     from `config/emulsify-core/vite/plugins.*` via {@link loadProjectExtensions}.
+ *  4. Assemble a base Vite config and optionally let the project extend/override
+ *     parts of it by returning a patch object from `extendConfig(...)`.
+ *
+ * Notes:
+ * - CSS & JS sourcemaps are enabled.
+ * - CSS assets keep their path and drop the internal `__style` suffix if present.
+ */
+
+import { defineConfig, mergeConfig } from 'vite';
+import path from 'node:path';
+
+import { resolveEnvironment } from './environment.js';
+import { makePlugins } from './plugins.js';
+import { buildInputs } from './entries.js';
+import { createSourceFileIndex } from './plugins/source-file-index.js';
+import { loadProjectExtensions } from './project-extensions.js';
+import { mergeReactSingletonResolve } from './utils/react-singleton.js';
+
+export default defineConfig(async () => {
+  /**
+   * Environment details for this build (project paths, platform, flags).
+   * @typedef {Object} EmulsifyEnv
+   * @property {string} projectDir - Absolute project root.
+   * @property {string} srcDir - Absolute source directory (`src/` if present, otherwise `components/`).
+   * @property {boolean} srcExists - Whether `src/` exists in the project.
+   * @property {string} platform - Deployment platform (e.g., `"drupal"`).
+   * @property {boolean} [SDC] - Single Directory Components toggle, if available.
+   * @property {boolean} [structureOverrides] - Whether component structure overrides are enabled.
+   * @property {string[]} [structureRoots] - Override roots, if provided.
+   * @property {object} [platformAdapter] - Active platform behavior adapter.
+   */
+
+  /** @type {EmulsifyEnv} */
+  const env = resolveEnvironment();
+  const sourceFileIndex = createSourceFileIndex(env.projectStructure);
+  const envWithSourceFileIndex = { ...env, sourceFileIndex };
+
+  // Build the Rollup/Vite entry map: keys encode output paths, values source files.
+  /** @type {Record<string, string>} */
+  const entries = buildInputs({
+    projectDir: env.projectDir,
+    srcDir: env.srcDir,
+    srcExists: env.srcExists,
+    isDrupal: env.platform === 'drupal',
+    SDC: env.SDC,
+    structureOverrides: env.structureOverrides,
+    structureRoots: env.structureRoots,
+    structureImplementations: env.structureImplementations,
+    projectStructure: env.projectStructure,
+    sourceFileIndex,
+  });
+
+  // Load optional project-provided plugins and config patches.
+  /**
+   * @type {{
+   *   projectPlugins: import('vite').PluginOption[],
+   *   extendConfig?: (base: import('vite').UserConfig, ctx: { env: EmulsifyEnv }) => import('vite').UserConfig
+   * }}
+   */
+  const { projectPlugins, extendConfig } = await loadProjectExtensions({ env });
+
+  // Assemble the base config before applying project extensions.
+  /** @type {import('vite').UserConfig} */
+  const base = {
+    // Treat the current working directory as the root.
+    root: process.cwd(),
+
+    // Core plugin set + project-provided plugins (if any).
+    plugins: [...makePlugins(envWithSourceFileIndex), ...projectPlugins],
+
+    // Keep React-based story helpers on the consumer project's React singleton.
+    resolve: mergeReactSingletonResolve(),
+
+    // Generate CSS sourcemaps in dev; JS sourcemaps are set in `build.sourcemap`.
+    css: {
+      devSourcemap: true,
+    },
+
+    build: {
+      // Clean the output directory before building.
+      emptyOutDir: true,
+
+      // All outputs are written into ./dist/
+      outDir: 'dist/',
+
+      // Emit production sourcemaps as well.
+      sourcemap: true,
+
+      rollupOptions: {
+        // Multi-entry input map constructed above.
+        input: entries,
+
+        // Keep file names deterministic and strip the internal CSS key suffix.
+        output: {
+          entryFileNames: '[name].js',
+
+          /**
+           * Decide asset filenames. Normalizes `.css` paths and removes the `__style`
+           * suffix used to avoid name collisions in entry keys.
+           * @param {import('rollup').PreRenderedAsset} assetInfo
+           * @returns {string}
+           */
+          assetFileNames: (assetInfo) => {
+            const file = assetInfo.name || assetInfo.fileName || '';
+            if (file.endsWith('.css')) {
+              // Drop the CSS key suffix used to avoid JS/CSS entry collisions.
+              return file.replace(/__style(?=\.css$)/, '');
+            }
+            const [original] = Array.isArray(assetInfo.originalFileNames)
+              ? assetInfo.originalFileNames
+              : assetInfo.originalFileName
+                ? [assetInfo.originalFileName]
+                : [];
+            if (original) {
+              const normalizedOriginal = path.normalize(original);
+              const relativeToProject = path.isAbsolute(normalizedOriginal)
+                ? path.relative(env.projectDir, normalizedOriginal)
+                : normalizedOriginal.replace(/^[/\\]+/, '');
+              const normalizedRelative = relativeToProject
+                .split(path.sep)
+                .join('/');
+              // Prevent traversing above dist/ if a relative path climbs directories.
+              const safePath = normalizedRelative.startsWith('..')
+                ? normalizedRelative.replace(/^(\.\.\/)+/g, '')
+                : normalizedRelative;
+              if (safePath) {
+                return safePath;
+              }
+            }
+            return 'assets/[name][extname]';
+          },
+        },
+      },
+    },
+
+    // Dev server tweaks; disable polling by default for performance.
+    server: {
+      watch: { usePolling: false },
+    },
+  };
+
+  // Let project extensions patch the final Vite config.
+  /** @type {import('vite').UserConfig} */
+  const patched =
+    typeof extendConfig === 'function'
+      ? mergeConfig(base, extendConfig(base, { env }) || {})
+      : base;
+
+  return patched;
+});

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@emulsify/core",
-  "version": "3.5.0",
-  "description": "Bundled tooling for Storybook development + Webpack Build",
+  "version": "4.0.1",
+  "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",
+    "craftcms",
     "design system",
     "drupal",
     "pattern library",
     "storybook",
-    "styleguide"
+    "styleguide",
+    "twig",
+    "vite",
+    "wordpress"
   ],
   "author": "Four Kitchens <shout@fourkitchens.com>",
   "license": "GPL-2.0",
@@ -16,6 +20,10 @@
     "node": ">=24"
   },
   "type": "module",
+  "bin": {
+    "emulsify-audit": "./scripts/audit.js",
+    "emulsify-audit-twig-stories": "./scripts/audit-twig-stories.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/emulsify-ds/emulsify-core.git"
@@ -24,6 +32,99 @@
     "url": "https://github.com/emulsify-ds/emulsify-core/issues"
   },
   "homepage": "https://github.com/emulsify-ds/emulsify-core#readme",
+  "files": [
+    ".cli/init.js",
+    ".storybook/_drupal.js",
+    ".storybook/css-components.js",
+    ".storybook/css-dist.js",
+    ".storybook/emulsifyTheme.js",
+    ".storybook/main.js",
+    ".storybook/manager.js",
+    ".storybook/preview.js",
+    ".storybook/utils.js",
+    "assets/**/*",
+    "config/.prettierrc.json",
+    "config/.stylelintrc.json",
+    "config/a11y.config.js",
+    "config/babel.config.js",
+    "config/eslint.config.js",
+    "config/postcss.config.js",
+    "config/vite/entries.js",
+    "config/vite/environment.js",
+    "config/vite/platforms.js",
+    "config/vite/plugins/copy-src-assets.js",
+    "config/vite/plugins/copy-twig-files.js",
+    "config/vite/plugins/css-asset-relativizer.js",
+    "config/vite/plugins/index.js",
+    "config/vite/plugins/mirror-components.js",
+    "config/vite/plugins/require-context.js",
+    "config/vite/plugins/source-file-index.js",
+    "config/vite/plugins/svg-sprite.js",
+    "config/vite/plugins/twig-extension-installers.js",
+    "config/vite/plugins/twig-module.js",
+    "config/vite/plugins/virtual-twig-asset-sources.js",
+    "config/vite/plugins/virtual-twig-globs.js",
+    "config/vite/plugins/vituum-patch.js",
+    "config/vite/plugins/yaml-module.js",
+    "config/vite/plugins.js",
+    "config/vite/project-config.js",
+    "config/vite/project-extensions.js",
+    "config/vite/project-structure.js",
+    "config/vite/twig-extensions.js",
+    "config/vite/utils/fs-safe.js",
+    "config/vite/utils/paths.js",
+    "config/vite/utils/react-singleton.js",
+    "config/vite/utils/unique.js",
+    "config/vite/vite.config.js",
+    "scripts/a11y.js",
+    "scripts/audit.js",
+    "scripts/audit-twig-stories.js",
+    "scripts/check-node-version.js",
+    "scripts/loadYaml.js",
+    "src/extensions/index.js",
+    "src/extensions/react/index.js",
+    "src/extensions/react/register.js",
+    "src/extensions/shared/attributes.js",
+    "src/extensions/shared/html.js",
+    "src/extensions/shared/lists.js",
+    "src/extensions/shared/object.js",
+    "src/extensions/twig/function-map.js",
+    "src/extensions/twig/functions/add-attributes.js",
+    "src/extensions/twig/functions/bem.js",
+    "src/extensions/twig/index.js",
+    "src/extensions/twig/register.js",
+    "src/extensions/twig/tag-map.js",
+    "src/extensions/twig/tags/switch.js",
+    "src/storybook/index.js",
+    "src/storybook/main-config.js",
+    "src/storybook/platform-behaviors.js",
+    "src/storybook/preview-parameters.js",
+    "src/storybook/render-twig.js",
+    "src/storybook/twig/include-function.js",
+    "src/storybook/twig/include.js",
+    "src/storybook/twig/drupal-filters.js",
+    "src/storybook/twig/reference-paths.js",
+    "src/storybook/twig/resolver.js",
+    "src/storybook/twig/setup.js",
+    "src/storybook/twig/source-events.js",
+    "src/storybook/twig/source-extensions.js",
+    "src/storybook/twig/source-function.js",
+    "src/storybook/twig/source.js"
+  ],
+  "exports": {
+    ".": "./src/extensions/index.js",
+    "./extensions": "./src/extensions/index.js",
+    "./extensions/react": "./src/extensions/react/index.js",
+    "./extensions/twig": "./src/extensions/twig/index.js",
+    "./storybook": "./src/storybook/index.js",
+    "./storybook/twig/drupal-filters": "./src/storybook/twig/drupal-filters.js",
+    "./storybook/twig/include-function": "./src/storybook/twig/include-function.js",
+    "./storybook/twig/source-function": "./src/storybook/twig/source-function.js",
+    "./storybook/twig/source": "./src/storybook/twig/source.js",
+    "./vite": "./config/vite/vite.config.js",
+    "./vite/plugins": "./config/vite/plugins.js",
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -31,113 +132,101 @@
     "scripts-prepend-node-path": "auto"
   },
   "scripts": {
-    "coverage": "npm run test && open-cli .coverage/lcov-report/index.html",
-    "format": "npm run lint-fix; npm run prettier-fix",
-    "husky:commit-msg": "commitlint --edit $1",
-    "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-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 -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"
+    "check-node-version": "node scripts/check-node-version.js",
+    "audit": "npm run check-node-version && node scripts/audit.js",
+    "audit:twig-stories": "npm run check-node-version && node scripts/audit-twig-stories.js",
+    "coverage": "npm run check-node-version && npm run test && open-cli .coverage/lcov-report/index.html",
+    "format": "npm run check-node-version && npm run lint-fix && npm run prettier-fix",
+    "fixtures:release": "npm run check-node-version && node scripts/release-fixtures.js",
+    "fixtures:release:list": "npm run check-node-version && node scripts/release-fixtures.js --list",
+    "husky:commit-msg": "npm run check-node-version && commitlint --edit $1",
+    "husky:pre-commit": "npm run check-node-version && npm run lint",
+    "lint": "npm run check-node-version && npm run lint-js && npm run prettier",
+    "lint-fix": "npm run check-node-version && npm run lint-js -- --fix",
+    "lint-js": "npm run check-node-version && eslint --config config/eslint.config.js ./.cli ./.storybook ./config ./scripts ./src",
+    "lint-staged": "npm run check-node-version && lint-staged",
+    "prepare": "npm run check-node-version && husky",
+    "prettier": "npm run check-node-version && prettier --check --config config/.prettierrc.json --ignore-unknown \"**/*.{js,mjs,cjs,jsx,json,yml,yaml,scss,md,twig}\"",
+    "prettier-fix": "npm run check-node-version && prettier --config config/.prettierrc.json --write --ignore-unknown \"**/*.{js,mjs,cjs,jsx,json,yml,yaml,scss,md,twig}\"",
+    "semantic-release": "npm run check-node-version && semantic-release --config ./release.config.cjs",
+    "version:develop": "npm run check-node-version && node scripts/bump-version-from-commits.js",
+    "storybook": "npm run check-node-version && NODE_OPTIONS=--no-deprecation storybook dev -p 6006 --no-open --exact-port",
+    "storybook-build": "npm run check-node-version && storybook build -o .out",
+    "storybook-deploy": "npm run check-node-version && storybook-to-ghpages -o .out",
+    "test": "npm run check-node-version && jest --coverage  --config ./config/jest.config.js",
+    "twatch": "npm run check-node-version && jest --no-coverage --watch --verbose"
   },
   "dependencies": {
-    "@babel/core": "^7.28.5",
-    "@babel/preset-env": "^7.28.5",
+    "@babel/core": "^7.28.4",
+    "@babel/eslint-parser": "^7.28.6",
+    "@babel/preset-env": "^7.28.3",
     "@emulsify/cli": "^1.11.4",
-    "@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",
+    "@eslint/js": "^9.39.4",
+    "@storybook/addon-a11y": "^10.1.4",
+    "@storybook/addon-links": "^10.1.4",
+    "@storybook/addon-themes": "^10.1.4",
+    "@storybook/react": "^10.1.4",
+    "@storybook/react-vite": "^10.1.4",
+    "@vituum/vite-plugin-twig": "^1.1.0",
     "autoprefixer": "^10.4.21",
-    "babel-loader": "^10.0.0",
     "babel-preset-minify": "^0.5.2",
-    "bem-twig-extension": "^0.1.1",
-    "breakpoint-sass": "^3.0.0",
-    "clean-webpack-plugin": "^4.0.0",
     "concurrently": "^9.2.1",
-    "copy-webpack-plugin": "^14.0.0",
-    "css-loader": "^7.1.1",
-    "eslint": "^10.1.0",
+    "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jest": "^29.15.1",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jest": "^29.0.1",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-security": "^4.0.0",
-    "file-loader": "^6.2.0",
-    "fs-extra": "^11.3.2",
+    "eslint-plugin-storybook": "^10.1.4",
+    "fs-extra": "^11.3.1",
     "glob": "^13.0.6",
     "graceful-fs": "^4.2.11",
-    "html-webpack-plugin": "^5.6.4",
-    "image-minimizer-webpack-plugin": "^5.0.0",
-    "imagemin": "^9.0.1",
-    "imagemin-jpegtran": "^8.0.0",
-    "imagemin-optipng": "^8.0.0",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "js-yaml": "^4.1.0",
-    "js-yaml-loader": "^1.2.2",
-    "mini-css-extract-plugin": "^2.9.4",
-    "node-sass-glob-importer": "^5.3.3",
     "normalize.css": "^8.0.1",
     "open-cli": "^9.0.0",
     "pa11y": "^9.0.1",
-    "postcss": "^8.5.6",
-    "postcss-loader": "^8.2.0",
+    "postcss": "^8.5.4",
     "postcss-scss": "^4.0.9",
     "ramda": "^0.32.0",
     "regenerator-runtime": "^0.14.1",
     "sass": "^1.93.2",
-    "sass-loader": "^16.0.6",
-    "storybook": "^9.1.20",
-    "style-dictionary": "^5.1.1",
-    "stylelint": "^17.7.0",
+    "storybook": "^10.1.4",
+    "stylelint": "^17.12.0",
     "stylelint-config-standard-scss": "^17.0.0",
     "stylelint-prettier": "^5.0.3",
-    "stylelint-webpack-plugin": "^5.0.1",
-    "svg-spritemap-webpack-plugin": "^5.0.3",
-    "terser-webpack-plugin": "^5.3.9",
-    "token-transformer": "^0.0.33",
+    "stylelint-selector-bem-pattern": "^5.0.0",
+    "twig": "^3.0.0",
     "twig-drupal-filters": "^3.2.0",
-    "twig-testing-library": "^1.2.0",
-    "twigjs-loader": "^1.0.3",
-    "webpack": "^5.102.1",
-    "webpack-cli": "^7.0.2",
-    "webpack-merge": "^6.0.1",
-    "webpack-remove-empty-scripts": "^1.1.1",
+    "vite": "^7.3.3",
+    "vite-plugin-sass-glob-import": "^6.0.0",
+    "vite-plugin-static-copy": "^4.1.0",
+    "vite-plugin-svg-sprite": "^0.7.0",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.1.0",
-    "@commitlint/config-conventional": "^20.0.0",
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
     "@semantic-release/changelog": "^6.0.2",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/github": "^12.0.8",
+    "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.0",
-    "all-contributors-cli": "^6.26.1",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.6",
+    "lint-staged": "^17.0.5",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "semantic-release": "^25.0.3"
   },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
   "overrides": {
-    "inflight": "^1.0.7",
-    "graceful-fs": "^4.2.11",
     "glob": "^13.0.6",
-    "rimraf": "^4.3.0",
-    "source-map-url": "^0.4.1",
-    "source-map-resolve": "^0.6.0",
-    "uuid": "^8.3.2"
+    "locutus": "^3.0.36",
+    "minimatch@3.0.x": "^3.1.5"
   }
 }