@emulsify/core 3.5.0 → 4.0.0

package/config/vite/plugins/require-context.js

@@ -0,0 +1,311 @@
+/**
+ * @file Webpack require.context compatibility for Vite.
+ *
+ * Some existing Emulsify stories still use Webpack's static
+ * `require.context()` helper to enumerate asset names. Vite does not define
+ * `require` in browser modules, so this plugin rewrites static calls to
+ * equivalent eager `import.meta.glob()` maps before import analysis runs.
+ */
+
+import { existsSync, readdirSync } from 'fs';
+import { dirname, relative, resolve } from 'path';
+import { toPosixPath } from '../utils/paths.js';
+
+const REQUIRE_CONTEXT_PATTERN =
+  /require\.context\(\s*(['"`])([^'"`]+)\1\s*,\s*(true|false)\s*,\s*\/((?:\\.|[^/\\])+)\/([dgimsuvy]*)\s*,?\s*\)/g;
+const STATIC_ASSET_CONTEXT_EXTS = new Set([
+  'avif',
+  'eot',
+  'gif',
+  'ico',
+  'jpeg',
+  'jpg',
+  'otf',
+  'pdf',
+  'png',
+  'svg',
+  'ttf',
+  'webp',
+  'woff',
+  'woff2',
+]);
+
+const REQUIRE_CONTEXT_HELPER = `
+const __emulsifyRequireContext = (modules, basePath, matcher) => {
+  const normalizeKey = (key) => key.startsWith('./') ? key : \`./\${key}\`;
+  const moduleKey = (key) => basePath + normalizeKey(key).slice(2);
+  const context = (key) => modules[moduleKey(key)];
+
+  context.keys = () =>
+    Object.keys(modules)
+      .map((key) => \`./\${key.slice(basePath.length)}\`)
+      .filter((key) => matcher.test(key))
+      .sort();
+  context.resolve = (key) => moduleKey(key);
+  context.id = basePath;
+
+  return context;
+};
+
+const __emulsifyRequireContextFromKeys = (keys, basePath, publicBasePath) => {
+  const normalizedKeys = keys.slice().sort();
+  const keySet = new Set(normalizedKeys);
+  const normalizeKey = (key) => key.startsWith('./') ? key : \`./\${key}\`;
+  const moduleKey = (key) => basePath + normalizeKey(key).slice(2);
+  const publicKey = (key) =>
+    publicBasePath ? publicBasePath + normalizeKey(key).slice(2) : moduleKey(key);
+  const context = (key) => keySet.has(normalizeKey(key)) ? publicKey(key) : undefined;
+
+  context.keys = () => normalizedKeys.slice();
+  context.resolve = (key) => moduleKey(key);
+  context.id = basePath;
+
+  return context;
+};
+`.trim();
+
+/**
+ * Determine whether a request is JavaScript-like source Vite should transform.
+ *
+ * @param {string} id - Vite module id.
+ * @returns {boolean} TRUE when the id is transformable JavaScript source.
+ */
+const isJavaScriptRequest = (id) =>
+  /\.[cm]?[jt]sx?(?:\?|$)/.test(id) && !id.includes('/node_modules/');
+
+/**
+ * Normalize a require.context directory argument for Vite glob keys.
+ *
+ * @param {string} request - Static directory request from require.context.
+ * @returns {string} Directory request with a trailing slash.
+ */
+const normalizeBasePath = (request) => {
+  if (request.endsWith('/')) return request;
+  if (request === '.') return './';
+  return `${request}/`;
+};
+
+/**
+ * Build a focused glob tail for the common extension-only regex shape.
+ *
+ * @param {string} regexSource - Source from a JavaScript regex literal.
+ * @returns {string} Glob tail.
+ */
+const globTailFromRegex = (regexSource) => {
+  const singleExtension = regexSource.match(/^\\\.([A-Za-z0-9]+)\$$/);
+  if (singleExtension) {
+    return `*.${singleExtension[1]}`;
+  }
+
+  const extensionGroup = regexSource.match(/^\\\.\(([-A-Za-z0-9_|]+)\)\$$/);
+  if (extensionGroup) {
+    return `*.{${extensionGroup[1].replaceAll('|', ',')}}`;
+  }
+
+  return '*';
+};
+
+/**
+ * Extract extension names from regexes that can be represented by a file glob.
+ *
+ * @param {string} regexSource - Source from a JavaScript regex literal.
+ * @returns {string[]} Lowercase extension names.
+ */
+const extensionsFromRegex = (regexSource) => {
+  const singleExtension = regexSource.match(/^\\\.([A-Za-z0-9]+)\$$/);
+  if (singleExtension) {
+    return [singleExtension[1].toLowerCase()];
+  }
+
+  const extensionGroup = regexSource.match(/^\\\.\(([-A-Za-z0-9_|]+)\)\$$/);
+  if (extensionGroup) {
+    return extensionGroup[1]
+      .split('|')
+      .filter(Boolean)
+      .map((extension) => extension.toLowerCase());
+  }
+
+  return [];
+};
+
+/**
+ * Remove stateful regex flags so repeated matcher.test() calls stay stable.
+ *
+ * @param {string} flags - Flags from a JavaScript regex literal.
+ * @returns {string} Non-stateful regex flags.
+ */
+const normalizeRegexFlags = (flags) => flags.replace(/[gy]/g, '');
+
+/**
+ * Resolve a static require.context directory against the importing module.
+ *
+ * @param {string} id - Vite module id.
+ * @param {string} request - Static directory request from require.context.
+ * @returns {string} Absolute filesystem directory path.
+ */
+const resolveContextDirectory = (id, request) => {
+  const importer = String(id || '').split('?')[0];
+  if (!importer || importer.includes('/node_modules/')) return '';
+
+  return resolve(dirname(importer), request);
+};
+
+/**
+ * Find files in a context directory and return Webpack-style context keys.
+ *
+ * @param {string} directory - Absolute context directory.
+ * @param {boolean} recursive - Whether nested directories are included.
+ * @param {RegExp} matcher - Context file matcher.
+ * @returns {string[]} Sorted `./file.ext` keys.
+ */
+function contextKeysFromDirectory(directory, recursive, matcher) {
+  const keys = [];
+
+  const visit = (currentDirectory) => {
+    for (const entry of readdirSync(currentDirectory, {
+      withFileTypes: true,
+    })) {
+      const absolutePath = resolve(currentDirectory, entry.name);
+      if (entry.isDirectory()) {
+        if (recursive) visit(absolutePath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      const key = `./${toPosixPath(relative(directory, absolutePath))}`;
+      if (matcher.test(key)) {
+        keys.push(key);
+      }
+    }
+  };
+
+  visit(directory);
+  return keys.sort();
+}
+
+/**
+ * Resolve a public URL base for root project asset directories.
+ *
+ * @param {string} directory - Absolute context directory.
+ * @returns {string} Public URL base, or an empty string when unknown.
+ */
+const publicBasePathForDirectory = (directory) => {
+  const relativeDirectory = toPosixPath(relative(process.cwd(), directory));
+
+  return relativeDirectory === 'assets' ||
+    relativeDirectory.startsWith('assets/')
+    ? `/${relativeDirectory.replace(/\/?$/, '/')}`
+    : '';
+};
+
+/**
+ * Build a key-only context for static assets to avoid module-importing files
+ * that Storybook may also serve through staticDirs.
+ *
+ * @param {{ id?: string, request: string, recursive: boolean, regexSource: string, regexFlags: string, basePath: string }} options
+ * Context details from the require.context call.
+ * @returns {string|null} Replacement source, or null when the directory cannot be enumerated.
+ */
+function staticAssetContextReplacement({
+  id,
+  request,
+  recursive,
+  regexSource,
+  regexFlags,
+  basePath,
+}) {
+  const extensions = extensionsFromRegex(regexSource);
+  if (
+    !extensions.length ||
+    !extensions.every((extension) => STATIC_ASSET_CONTEXT_EXTS.has(extension))
+  ) {
+    return null;
+  }
+
+  const directory = resolveContextDirectory(id, request);
+  if (!directory || !existsSync(directory)) return null;
+
+  const matcher = new RegExp(regexSource, normalizeRegexFlags(regexFlags));
+  const keys = contextKeysFromDirectory(directory, recursive, matcher);
+  const publicBasePath = publicBasePathForDirectory(directory);
+
+  return (
+    '__emulsifyRequireContextFromKeys(' +
+    `${JSON.stringify(keys)}, ` +
+    `${JSON.stringify(basePath)}, ` +
+    `${JSON.stringify(publicBasePath)}` +
+    ')'
+  );
+}
+
+/**
+ * Transform static require.context calls into Vite import.meta.glob calls.
+ *
+ * @param {string} source - JavaScript source.
+ * @param {string} [id=''] - Vite module id.
+ * @returns {string|null} Transformed source, or null when unchanged.
+ */
+export function transformRequireContext(source, id = '') {
+  const replacements = [];
+  let match;
+
+  REQUIRE_CONTEXT_PATTERN.lastIndex = 0;
+  while ((match = REQUIRE_CONTEXT_PATTERN.exec(source))) {
+    const [, , request, recursive, regexSource, regexFlags] = match;
+    const basePath = normalizeBasePath(request);
+    const globTail = globTailFromRegex(regexSource);
+    const globPattern = `${basePath}${recursive === 'true' ? '**/' : ''}${globTail}`;
+    const matcherFlags = normalizeRegexFlags(regexFlags);
+    const staticAssetReplacement = staticAssetContextReplacement({
+      basePath,
+      id,
+      recursive: recursive === 'true',
+      regexFlags,
+      regexSource,
+      request,
+    });
+    const replacement =
+      staticAssetReplacement ||
+      '__emulsifyRequireContext(' +
+        `import.meta.glob(${JSON.stringify(globPattern)}, { eager: true, import: 'default' }), ` +
+        `${JSON.stringify(basePath)}, ` +
+        `new RegExp(${JSON.stringify(regexSource)}, ${JSON.stringify(matcherFlags)})` +
+        ')';
+
+    replacements.push({
+      end: REQUIRE_CONTEXT_PATTERN.lastIndex,
+      replacement,
+      start: match.index,
+    });
+  }
+
+  if (!replacements.length) return null;
+
+  let transformed = source;
+  for (const { start, end, replacement } of replacements.reverse()) {
+    transformed =
+      transformed.slice(0, start) + replacement + transformed.slice(end);
+  }
+
+  return `${REQUIRE_CONTEXT_HELPER}\n\n${transformed}`;
+}
+
+/**
+ * Rewrite static Webpack require.context calls for Vite-powered stories.
+ *
+ * @returns {import('vite').PluginOption} Vite plugin.
+ */
+export function requireContextCompatPlugin() {
+  return {
+    name: 'emulsify-require-context-compat',
+    enforce: 'pre',
+    transform(source, id) {
+      if (!isJavaScriptRequest(id) || !source.includes('require.context')) {
+        return null;
+      }
+
+      const code = transformRequireContext(source, id);
+      return code ? { code, map: null } : null;
+    },
+  };
+}

package/config/vite/plugins/source-file-index.js

@@ -0,0 +1,184 @@
+/**
+ * @file Source file discovery helpers shared by Emulsify Vite copy plugins.
+ *
+ * This module walks resolved source roots once, then exposes filtered views for
+ * component and global files so copy plugins share the same filesystem model.
+ */
+
+import { readdirSync } from 'fs';
+import { join, relative, sep } from 'path';
+
+import { relativeFrom } from '../project-structure.js';
+
+const DEFAULT_SKIP_DIRS = [
+  'node_modules',
+  '.git',
+  '.cache',
+  '.vite',
+  '.out',
+  '.coverage',
+  'dist',
+];
+
+/**
+ * Depth-first walk to list every file under a given root.
+ *
+ * @param {string} rootDir - Directory to traverse.
+ * @param {{
+ *   shouldSkipDir?: (dir: string) => boolean,
+ *   useDefaultSkips?: boolean
+ * }} [options] - Traversal options.
+ * @returns {string[]} Absolute file paths.
+ */
+export function walkFiles(
+  rootDir,
+  { shouldSkipDir = () => false, useDefaultSkips = true } = {},
+) {
+  const files = [];
+  const stack = [rootDir];
+
+  while (stack.length) {
+    const currentDir = stack.pop();
+    if (!currentDir) continue;
+
+    let entryNames = [];
+    try {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      entryNames = readdirSync(currentDir, { withFileTypes: true }).sort(
+        (a, b) => a.name.localeCompare(b.name),
+      );
+    } catch {
+      // Skip unreadable directories and keep walking the remaining stack.
+      continue;
+    }
+
+    for (const entry of entryNames) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (shouldSkipDir(fullPath)) continue;
+        if (useDefaultSkips && DEFAULT_SKIP_DIRS.includes(entry.name)) {
+          continue;
+        }
+        stack.push(fullPath);
+      } else if (entry.isFile()) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Determine whether a directory is the same as, or nested inside, another one.
+ *
+ * @param {string} candidateDir - Directory to test.
+ * @param {string} rootDir - Boundary directory.
+ * @returns {boolean} TRUE when candidateDir is the root or inside it.
+ */
+export function isSameOrInsideDir(candidateDir, rootDir) {
+  const rel = relative(rootDir, candidateDir);
+  return !rel || (!rel.startsWith('..') && !rel.includes(`..${sep}`));
+}
+
+/**
+ * Determine whether a file is component metadata copied beside Twig templates.
+ *
+ * @param {string} filePath - Absolute or relative file path.
+ * @returns {boolean} TRUE for component metadata files.
+ */
+export const isComponentMetadataFile = (filePath) =>
+  /\.component\.(yml|yaml|json)$/i.test(filePath);
+
+/**
+ * Determine whether a file should be copied by the static asset pass.
+ *
+ * @param {string} filePath - Absolute or relative file path.
+ * @returns {boolean} TRUE for non-code source assets.
+ */
+export const isStaticSourceAsset = (filePath) =>
+  !/\.(jsx?|scss|twig|map)$/i.test(filePath) &&
+  !isComponentMetadataFile(filePath);
+
+/**
+ * Build the roots that should not be crawled during a global source pass.
+ *
+ * @param {{ directory: string }} globalRoot - Global source root record.
+ * @param {{ directory: string }[]} componentRoots - Component source root records.
+ * @returns {string[]} Directory paths to skip.
+ */
+const globalTraversalSkipRoots = (globalRoot, componentRoots) => {
+  const configuredSkips = [
+    join(globalRoot.directory, 'components'),
+    join(globalRoot.directory, 'util'),
+  ];
+  const nestedComponentRoots = componentRoots
+    .map((root) => root.directory)
+    .filter(
+      (directory) =>
+        directory !== globalRoot.directory &&
+        isSameOrInsideDir(directory, globalRoot.directory),
+    );
+
+  return [...configuredSkips, ...nestedComponentRoots];
+};
+
+/**
+ * Create a lazy, shared index of files under the resolved project source roots.
+ * Accessors return the same array reference between calls for a single index
+ * instance once the file tree has been built.
+ *
+ * @param {object} structure - Resolved project structure.
+ * @returns {{
+ *   all: () => Array<object>,
+ *   componentFiles: () => Array<object>,
+ *   globalFiles: () => Array<object>
+ * }} Indexed file accessors.
+ */
+export function createSourceFileIndex(structure) {
+  let indexedFiles = null;
+  let componentFilesArr = null;
+  let globalFilesArr = null;
+
+  const indexRoot = (root, rootType, options = {}) =>
+    walkFiles(root.directory, options).map((absPath) => ({
+      absPath,
+      relPath: relativeFrom(absPath, root.directory),
+      root,
+      rootType,
+    }));
+
+  const build = () => {
+    if (indexedFiles) return indexedFiles;
+
+    componentFilesArr = structure.componentRootRecords.flatMap((root) =>
+      indexRoot(root, 'component'),
+    );
+    globalFilesArr = structure.globalRootRecords.flatMap((root) => {
+      const skipRoots = globalTraversalSkipRoots(
+        root,
+        structure.componentRootRecords,
+      );
+
+      return indexRoot(root, 'global', {
+        shouldSkipDir: (directory) =>
+          skipRoots.some((skipRoot) => isSameOrInsideDir(directory, skipRoot)),
+      });
+    });
+
+    indexedFiles = [...componentFilesArr, ...globalFilesArr];
+    return indexedFiles;
+  };
+
+  return {
+    all: build,
+    componentFiles: () => {
+      build();
+      return componentFilesArr;
+    },
+    globalFiles: () => {
+      build();
+      return globalFilesArr;
+    },
+  };
+}

package/config/vite/plugins/svg-sprite.js

@@ -0,0 +1,117 @@
+/**
+ * @file SVG sprite file plugin.
+ *
+ * Builds a physical `dist/assets/icons.svg` sprite from configured SVG globs so
+ * Drupal and static consumers can reference a stable emitted spritemap asset.
+ */
+
+import { readFileSync } from 'fs';
+import { basename } from 'path';
+import { globSync } from 'glob';
+
+import { toPosixPath } from '../utils/paths.js';
+import { unique } from '../utils/unique.js';
+
+/**
+ * Builds a single SVG sprite file from a set of icon globs.
+ *
+ * @param {{ include: string|string[], symbolId?: string }} options - Plugin options.
+ * @returns {import('vite').PluginOption} SVG sprite plugin.
+ */
+export function svgSpriteFilePlugin({ include, symbolId = '[name]' }) {
+  const toArray = (x) => (Array.isArray(x) ? x : [x]).filter(Boolean);
+
+  /** @type {string[]} */
+  let patterns = [];
+  /** @type {string[]} */
+  let iconFiles = [];
+  let iconFilesResolved = false;
+
+  const collectIconFiles = () => {
+    if (iconFilesResolved) return iconFiles;
+    iconFiles = unique(
+      patterns.flatMap((p) => globSync(p)).filter(Boolean),
+    ).sort((a, b) => toPosixPath(a).localeCompare(toPosixPath(b)));
+    iconFilesResolved = true;
+    return iconFiles;
+  };
+
+  return {
+    name: 'emulsify-svg-sprite-file',
+    apply: 'build',
+
+    /** Register icons for watch. */
+    buildStart() {
+      patterns = toArray(include).map(toPosixPath);
+      iconFilesResolved = false;
+      for (const f of collectIconFiles()) {
+        try {
+          this.addWatchFile(f);
+        } catch {
+          /* noop */
+        }
+      }
+    },
+
+    /** Concatenate all matched SVGs into a single sprite. */
+    generateBundle() {
+      const files = collectIconFiles();
+
+      if (!files.length) return;
+
+      const used = new Set();
+      const makeId = (abs) => {
+        const stem = basename(abs).replace(/\.svg$/i, '');
+        let id = symbolId
+          .replace('[name]', stem)
+          .toLowerCase()
+          .replace(/[^a-z0-9_-]+/g, '-')
+          .replace(/^-+|-+$/g, '');
+        if (!used.has(id)) {
+          used.add(id);
+          return id;
+        }
+        let i = 2;
+        while (used.has(`${id}-${i}`)) i += 1;
+        id = `${id}-${i}`;
+        used.add(id);
+        return id;
+      };
+
+      const symbols = files
+        .map((abs) => {
+          let content = '';
+          try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename
+            content = readFileSync(abs, 'utf8');
+          } catch {
+            return '';
+          }
+          const m = content.match(/<svg\b([^>]*)>([\s\S]*?)<\/svg>/i);
+          const inner = (m ? m[2] : content)
+            .replace(/<\/*symbol[^>]*>/gi, '')
+            .replace(/<\/*defs[^>]*>/gi, '')
+            // Drop namespace-prefixed attributes that lose their prefix in the merged sprite.
+            .replace(/\s+[a-zA-Z0-9_-]+:[a-zA-Z0-9_.-]+="[^"]*"/g, '')
+            .trim();
+          const attrs = m ? m[1] : '';
+          const vb = attrs.match(/\bviewBox="([^"]+)"/i);
+          const viewBoxAttr = vb ? ` viewBox="${vb[1]}"` : '';
+          return `<symbol id="${makeId(abs)}"${viewBoxAttr}>${inner}</symbol>`;
+        })
+        .filter(Boolean);
+
+      const sprite = [
+        '<svg xmlns="http://www.w3.org/2000/svg" style="display:none">',
+        ...symbols,
+        '</svg>\n',
+      ].join('\n');
+
+      this.emitFile({
+        type: 'asset',
+        fileName: 'assets/icons.svg',
+        source: sprite,
+      });
+    },
+  };
+}

package/config/vite/plugins/twig-extension-installers.js

@@ -0,0 +1,36 @@
+/**
+ * @file Virtual Twig.js extension installer module for Storybook.
+ */
+
+import { generateTwigExtensionInstallersModule } from '../twig-extensions.js';
+
+export const VIRTUAL_TWIG_EXTENSION_INSTALLERS_ID =
+  'virtual:emulsify-twig-extension-installers';
+
+const resolvedVirtualTwigExtensionInstallersId = `\0${VIRTUAL_TWIG_EXTENSION_INSTALLERS_ID}`;
+
+/**
+ * Provide configured Twig.js extension installers to browser-rendered modules.
+ *
+ * @param {object} [env={}] - Normalized Emulsify environment.
+ * @returns {import('vite').PluginOption} Vite virtual module plugin.
+ */
+export function virtualTwigExtensionInstallersPlugin(env = {}) {
+  return {
+    name: 'emulsify-virtual-twig-extension-installers',
+    resolveId(id) {
+      if (id === VIRTUAL_TWIG_EXTENSION_INSTALLERS_ID) {
+        return resolvedVirtualTwigExtensionInstallersId;
+      }
+
+      return null;
+    },
+    load(id) {
+      if (id === resolvedVirtualTwigExtensionInstallersId) {
+        return generateTwigExtensionInstallersModule(env);
+      }
+
+      return null;
+    },
+  };
+}