@emulsify/core 3.5.0 → 4.0.1

package/src/storybook/twig/reference-paths.js

@@ -0,0 +1,294 @@
+/**
+ * @file Node-safe Twig reference path helpers shared by audit and Storybook.
+ *
+ * Twig root records are memoized per environment object so repeated runtime
+ * include resolution can reuse the same normalized root list within a session.
+ */
+
+import { unique } from '../../extensions/shared/lists.js';
+
+const ENV = (typeof __EMULSIFY_ENV__ !== 'undefined' && __EMULSIFY_ENV__) || {};
+
+/** @type {WeakMap<object, object[]>} */
+let rootRecordsCache = new WeakMap();
+
+/** @type {object[]|undefined} */
+let defaultRecords;
+
+const normalizeGlobPath = (filePath) => filePath.replace(/\\/g, '/');
+
+/**
+ * Convert an absolute project path to a Vite root-relative key.
+ *
+ * @param {string} absolutePath - Absolute file or directory path.
+ * @param {object} env - Normalized Emulsify environment.
+ * @returns {string} Root-relative path with a leading slash.
+ */
+export function toRootRelativePath(absolutePath, env = ENV) {
+  if (!absolutePath) return '';
+
+  const normalizedPath = normalizeGlobPath(absolutePath);
+  const projectDir = normalizeGlobPath(env?.projectDir || '');
+
+  if (projectDir && normalizedPath.startsWith(projectDir)) {
+    const relativePath = normalizedPath.slice(projectDir.length);
+    return relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+  }
+
+  return normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`;
+}
+
+/**
+ * Normalize a Twig root declaration into resolver metadata.
+ *
+ * @param {{name?: string, directory?: string}|string} root - Root declaration.
+ * @param {object} env - Normalized Emulsify environment.
+ * @returns {{name: string|undefined, directory: string, rootRel: string}|null}
+ */
+function normalizeRootRecord(root, env) {
+  const directory = typeof root === 'string' ? root : root?.directory;
+  if (!directory) return null;
+
+  return {
+    name: typeof root === 'string' ? undefined : root.name,
+    directory,
+    rootRel: toRootRelativePath(directory, env),
+  };
+}
+
+/**
+ * Compute Twig roots from the normalized project structure.
+ *
+ * @param {object} env - Normalized Emulsify environment.
+ * @returns {{name: string|undefined, directory: string, rootRel: string}[]}
+ *   Twig roots in resolution order.
+ */
+function computeTwigRootRecords(env) {
+  const structure = env?.projectStructure || {};
+  const namespaceRoots =
+    structure.namespaceRoots && typeof structure.namespaceRoots === 'object'
+      ? structure.namespaceRoots
+      : env?.namespaceRoots && typeof env.namespaceRoots === 'object'
+        ? env.namespaceRoots
+        : {};
+  const namedRoots = [
+    ...(Array.isArray(structure.componentRootRecords)
+      ? structure.componentRootRecords
+      : []),
+    ...(Array.isArray(env?.structureImplementations)
+      ? env.structureImplementations
+      : []),
+    ...Object.entries(namespaceRoots).map(([name, directory]) => ({
+      name,
+      directory,
+    })),
+  ];
+  const unnamedRoots = [
+    ...(Array.isArray(structure.twigRoots) ? structure.twigRoots : []),
+    ...(Array.isArray(env?.componentRoots) ? env.componentRoots : []),
+    ...(env?.srcDir ? [env.srcDir] : []),
+  ];
+  const fallbackRoots = env?.projectDir
+    ? [
+        `${env.projectDir}/src`,
+        `${env.projectDir}/src/components`,
+        `${env.projectDir}/components`,
+      ]
+    : ['/src', '/src/components', '/components'];
+  const records = [...namedRoots, ...unnamedRoots, ...fallbackRoots]
+    .map((root) => normalizeRootRecord(root, env))
+    .filter(Boolean);
+
+  return unique(
+    records.map((record) => `${record.name || ''}|${record.rootRel}`),
+  )
+    .map((key) =>
+      records.find(
+        (record) => `${record.name || ''}|${record.rootRel}` === key,
+      ),
+    )
+    .filter(Boolean);
+}
+
+/**
+ * Build Twig roots from the normalized project structure.
+ *
+ * @param {object} [env=ENV] - Normalized Emulsify environment.
+ * @returns {{name: string|undefined, directory: string, rootRel: string}[]}
+ *   Twig roots in resolution order.
+ */
+export function buildTwigRootRecords(env = ENV) {
+  if (env === ENV) {
+    defaultRecords ||= computeTwigRootRecords(env);
+    return defaultRecords;
+  }
+
+  if (env && typeof env === 'object') {
+    const cached = rootRecordsCache.get(env);
+    if (cached) return cached;
+
+    const records = computeTwigRootRecords(env);
+    rootRecordsCache.set(env, records);
+    return records;
+  }
+
+  return computeTwigRootRecords(env);
+}
+
+/**
+ * Reset memoized Twig root records for tests.
+ *
+ * @param {object} [env] - Optional environment object to clear.
+ */
+export function resetTwigRootRecordsCache(env) {
+  if (arguments.length === 0) {
+    rootRecordsCache = new WeakMap();
+    defaultRecords = undefined;
+    return;
+  }
+
+  if (env === ENV) {
+    defaultRecords = undefined;
+    return;
+  }
+
+  if (env && typeof env === 'object') {
+    rootRecordsCache.delete(env);
+  }
+}
+
+/**
+ * Remove a Twig file extension from a reference.
+ *
+ * @param {string} value - Template reference.
+ * @returns {string} Reference without `.twig` or `.html.twig`.
+ */
+function removeTwigExtension(value) {
+  return value.replace(/\.html\.twig$/i, '').replace(/\.twig$/i, '');
+}
+
+/**
+ * Build candidate keys below one root for a template reference.
+ *
+ * @param {string} rootRel - Root-relative Twig root.
+ * @param {string} reference - Template reference relative to the root.
+ * @returns {string[]} Candidate Vite glob keys.
+ */
+export function candidateKeysForRoot(rootRel, reference) {
+  const cleanReference = reference.replace(/^[./]+/, '').replace(/^\/+/, '');
+  const hasHtmlExtension = /\.html\.twig$/i.test(cleanReference);
+  const hasTwigExtension = /\.twig$/i.test(cleanReference);
+  const withoutExtension = removeTwigExtension(cleanReference);
+  const stem = withoutExtension.split('/').pop();
+  const explicitCandidates = hasHtmlExtension
+    ? [
+        `${rootRel}/${withoutExtension}.html.twig`,
+        `${rootRel}/${withoutExtension}.twig`,
+      ]
+    : [
+        `${rootRel}/${withoutExtension}.twig`,
+        `${rootRel}/${withoutExtension}.html.twig`,
+      ];
+  const shorthandCandidates = [
+    `${rootRel}/${withoutExtension}/${stem}.twig`,
+    `${rootRel}/${withoutExtension}/${stem}.html.twig`,
+    ...explicitCandidates,
+  ];
+
+  return unique(
+    (hasTwigExtension || withoutExtension.includes('/')
+      ? explicitCandidates
+      : shorthandCandidates
+    ).map((key) => key.replace(/\/{2,}/g, '/')),
+  );
+}
+
+/**
+ * Find root records for a namespace.
+ *
+ * @param {string} namespace - Namespace name.
+ * @param {{name?: string}[]} roots - Twig root records.
+ * @returns {object[]} Matching root records.
+ */
+function rootsForNamespace(namespace, roots) {
+  return roots.filter((root) => root.name === namespace);
+}
+
+/**
+ * Parse a Twig template reference into namespace and relative path parts.
+ *
+ * @param {string} name - Template reference.
+ * @returns {{namespace?: string, path: string, shorthand?: boolean}|null}
+ */
+function parseTemplateReference(name) {
+  if (typeof name !== 'string' || !name.trim()) return null;
+
+  const cleanName = name.trim();
+  const colonMatch = cleanName.match(/^([^:/.]+):(.+)$/);
+  if (colonMatch) {
+    return {
+      namespace: colonMatch[1],
+      path: colonMatch[2],
+    };
+  }
+
+  const atMatch = cleanName.match(/^@([^/]+)\/(.+)$/);
+  if (atMatch) {
+    return {
+      namespace: atMatch[1],
+      path: atMatch[2],
+    };
+  }
+
+  if (cleanName.startsWith('@')) {
+    return {
+      path: cleanName.slice(1),
+      shorthand: true,
+    };
+  }
+
+  const slashMatch = cleanName.match(/^([^/]+)\/(.+)$/);
+  if (slashMatch) {
+    return {
+      namespace: slashMatch[1],
+      path: slashMatch[2],
+    };
+  }
+
+  return {
+    path: cleanName,
+    shorthand: true,
+  };
+}
+
+/**
+ * Build candidate Vite glob keys for a Twig reference.
+ *
+ * @param {string} name - Template reference.
+ * @param {object} env - Normalized Emulsify environment.
+ * @returns {string[]} Candidate Vite glob keys.
+ */
+export function candidateKeysForReference(name, env = ENV) {
+  const roots = buildTwigRootRecords(env);
+  const parsed = parseTemplateReference(name);
+  if (!parsed) return [];
+
+  const projectNamespace = env?.machineName;
+  const namespaceRoots =
+    parsed.namespace && parsed.namespace !== projectNamespace
+      ? rootsForNamespace(parsed.namespace, roots)
+      : [];
+  const searchRoots = namespaceRoots.length ? namespaceRoots : roots;
+  const searchPaths = unique([
+    parsed.path,
+    ...(parsed.namespace && !namespaceRoots.length
+      ? [`${parsed.namespace}/${parsed.path}`]
+      : []),
+  ]);
+
+  return unique(
+    searchRoots.flatMap((root) =>
+      searchPaths.flatMap((part) => candidateKeysForRoot(root.rootRel, part)),
+    ),
+  );
+}

package/src/storybook/twig/resolver.js

@@ -0,0 +1,318 @@
+/**
+ * @file Runtime Twig template resolver used by Storybook Twig helpers.
+ */
+
+import {
+  modules as twigModules,
+  sources as twigSources,
+} from 'virtual:emulsify-twig-globs';
+import {
+  buildTwigRootRecords,
+  candidateKeysForReference,
+} from './reference-paths.js';
+
+export {
+  buildTwigRootRecords,
+  candidateKeysForReference,
+  candidateKeysForRoot,
+  toRootRelativePath,
+} from './reference-paths.js';
+
+const ENV = (typeof __EMULSIFY_ENV__ !== 'undefined' && __EMULSIFY_ENV__) || {};
+
+/**
+ * Resolve a value from a Vite glob map.
+ *
+ * @param {Record<string, *>} map - Vite glob map.
+ * @param {string[]} candidates - Candidate map keys.
+ * @returns {*} Resolved map value.
+ */
+function resolveFromMap(map, candidates) {
+  for (const key of candidates) {
+    // Vite glob map keys are generated from static Storybook patterns.
+    // eslint-disable-next-line security/detect-object-injection
+    const value = map[key];
+    if (value) {
+      return value.default ?? value;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Build grouped component fallback suffixes from exact candidate keys.
+ *
+ * Projects can keep components under grouping directories such as
+ * `src/components/ui/heading/heading.twig`, while project-scoped component IDs
+ * use only the component name, such as `project:heading`. Exact candidates
+ * remain preferred; these suffixes only run after direct lookup misses.
+ *
+ * @param {string[]} candidates - Exact candidate Vite glob keys.
+ * @param {object} env - Normalized Emulsify environment.
+ * @returns {{rootRel: string, suffix: string}[]} Root-scoped fallback suffixes.
+ */
+function groupedComponentSuffixes(candidates, env) {
+  const roots = buildTwigRootRecords(env)
+    .map((root) => root.rootRel)
+    .filter(Boolean)
+    .sort((left, right) => right.length - left.length);
+  const suffixes = [];
+  const seen = new Set();
+
+  for (const candidate of candidates) {
+    for (const rootRel of roots) {
+      const normalizedRoot = rootRel.replace(/\/+$/, '');
+      const prefix = `${normalizedRoot}/`;
+      if (!candidate.startsWith(prefix)) continue;
+
+      const suffix = candidate.slice(normalizedRoot.length);
+      const key = `${normalizedRoot}|${suffix}`;
+      if (!seen.has(key)) {
+        suffixes.push({ rootRel: normalizedRoot, suffix });
+        seen.add(key);
+      }
+      break;
+    }
+  }
+
+  return suffixes;
+}
+
+/**
+ * Resolve a Twig glob entry by grouped component suffix.
+ *
+ * @param {Record<string, *>} map - Vite glob map.
+ * @param {string[]} candidates - Exact candidate Vite glob keys.
+ * @param {object} env - Normalized Emulsify environment.
+ * @returns {{key: string, value: *}|undefined} Matched glob entry.
+ */
+function findGroupedComponentEntry(map, candidates, env) {
+  const entries = Object.entries(map);
+
+  for (const { rootRel, suffix } of groupedComponentSuffixes(candidates, env)) {
+    const rootPrefix = `${rootRel}/`;
+    const match = entries.find(
+      ([key]) => key.startsWith(rootPrefix) && key.endsWith(suffix),
+    );
+    if (match) {
+      return { key: match[0], value: match[1] };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Find a Vite glob map entry and keep its key for cache lookups.
+ *
+ * @param {Record<string, *>} map - Vite glob map.
+ * @param {string[]} candidates - Candidate map keys.
+ * @returns {{key: string, value: *}|undefined} Matched glob entry.
+ */
+function findGlobEntry(map, candidates) {
+  for (const key of candidates) {
+    if (Object.hasOwnProperty.call(map, key)) {
+      // Vite glob map keys are generated from static Storybook patterns.
+      // eslint-disable-next-line security/detect-object-injection
+      return { key, value: map[key] };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Find a direct or grouped component Vite glob entry.
+ *
+ * @param {Record<string, *>} map - Vite glob map.
+ * @param {string[]} candidates - Exact candidate Vite glob keys.
+ * @param {object} env - Normalized Emulsify environment.
+ * @returns {{key: string, value: *}|undefined} Matched glob entry.
+ */
+function findTemplateEntry(map, candidates, env) {
+  return (
+    findGlobEntry(map, candidates) ||
+    findGroupedComponentEntry(map, candidates, env)
+  );
+}
+
+/**
+ * Normalize raw source loader output from Vite import forms.
+ *
+ * @param {*} value - Raw source value or imported module.
+ * @returns {string|undefined} Raw source text.
+ */
+function normalizeSourceText(value) {
+  const source = value?.default ?? value;
+  return typeof source === 'string' ? source : undefined;
+}
+
+/**
+ * Create a Twig resolver bound to a normalized environment and Vite maps.
+ *
+ * @param {{
+ *   env?: object,
+ *   modules?: Record<string, *>,
+ *   sources?: Record<string, string|Function>
+ * }} options - Resolver inputs.
+ * @returns {{
+ *   resolveTemplate: Function,
+ *   resolveTemplateSource: Function,
+ *   isTemplateSourceLoading: Function,
+ *   whenTemplateSourceLoaded: Function,
+ *   candidateKeysForReference: Function
+ * }} Resolver functions.
+ */
+export function createTwigResolver({
+  env = ENV,
+  modules = twigModules,
+  sources = twigSources,
+} = {}) {
+  const sourceTextCache = new Map();
+  const sourceLoadPromises = new Map();
+
+  const findSourceEntry = (name) => {
+    const candidates = candidateKeysForReference(name, env);
+
+    return (
+      findGlobEntry(sources, [name]) ||
+      findTemplateEntry(sources, candidates, env)
+    );
+  };
+
+  const resolveSourceEntry = (entry) => {
+    if (!entry) return undefined;
+    if (sourceTextCache.has(entry.key)) {
+      return sourceTextCache.get(entry.key);
+    }
+
+    const sourceText = normalizeSourceText(entry.value);
+    if (typeof sourceText === 'string') {
+      sourceTextCache.set(entry.key, sourceText);
+      return sourceText;
+    }
+
+    if (
+      typeof entry.value === 'function' &&
+      !sourceLoadPromises.has(entry.key)
+    ) {
+      let loadedSource;
+      try {
+        loadedSource = entry.value();
+      } catch (error) {
+        loadedSource = Promise.reject(error);
+      }
+
+      const sourceLoad = Promise.resolve(loadedSource)
+        .then((loaded) => {
+          const loadedText = normalizeSourceText(loaded);
+          if (typeof loadedText === 'string') {
+            sourceTextCache.set(entry.key, loadedText);
+          }
+          return loadedText;
+        })
+        .catch((error) => {
+          console.error(`source(): failed to load ${entry.key}`, error);
+          return undefined;
+        })
+        .finally(() => {
+          sourceLoadPromises.delete(entry.key);
+        });
+
+      sourceLoadPromises.set(entry.key, sourceLoad);
+    }
+
+    return undefined;
+  };
+
+  const isTemplateSourceLoading = (name) => {
+    const entry = findSourceEntry(name);
+    return !!entry && sourceLoadPromises.has(entry.key);
+  };
+
+  const whenTemplateSourceLoaded = (name) => {
+    const entry = findSourceEntry(name);
+    return entry ? sourceLoadPromises.get(entry.key) : undefined;
+  };
+
+  return {
+    candidateKeysForReference: (name) => candidateKeysForReference(name, env),
+    resolveTemplate(name) {
+      // Direct lookups support callers that already resolved a Vite glob key.
+      // eslint-disable-next-line security/detect-object-injection
+      const direct = modules[name];
+      if (direct) {
+        return direct.default ?? direct;
+      }
+
+      const candidates = candidateKeysForReference(name, env);
+      const template = resolveFromMap(modules, candidates);
+      if (template) {
+        return template;
+      }
+
+      const groupedEntry = findGroupedComponentEntry(modules, candidates, env);
+      if (groupedEntry) {
+        return groupedEntry.value.default ?? groupedEntry.value;
+      }
+
+      return undefined;
+    },
+    isTemplateSourceLoading,
+    resolveTemplateSource(name) {
+      return resolveSourceEntry(findSourceEntry(name));
+    },
+    whenTemplateSourceLoaded,
+  };
+}
+
+let defaultResolver;
+
+/**
+ * Lazily create the default resolver after virtual Twig glob bindings settle.
+ *
+ * The virtual Twig glob module eagerly imports compiled Twig modules. Those
+ * modules register source(), which imports this resolver while the virtual glob
+ * module may still be initializing. Deferring the default resolver avoids
+ * reading virtual module bindings during that circular module setup.
+ *
+ * @returns {ReturnType<typeof createTwigResolver>} Default Twig resolver.
+ */
+function getDefaultResolver() {
+  if (!defaultResolver) {
+    defaultResolver = createTwigResolver();
+  }
+
+  return defaultResolver;
+}
+
+/**
+ * Resolve a template identifier to a compiled Twig render function.
+ *
+ * @param {string} name - Template identifier.
+ * @returns {Function|undefined} Render function when available.
+ */
+export default function resolveTemplate(name) {
+  return getDefaultResolver().resolveTemplate(name);
+}
+
+/**
+ * Resolve a template identifier to raw Twig source.
+ *
+ * Lazy raw-source glob entries return `undefined` on first request while their
+ * dynamic import resolves. The loaded text is cached and returned on a later
+ * call, which usually happens after the Storybook Twig renderer re-renders.
+ *
+ * @param {string} name - Template identifier.
+ * @returns {string|undefined} Raw Twig source when available.
+ */
+export function resolveTemplateSource(name) {
+  return getDefaultResolver().resolveTemplateSource(name);
+}
+
+resolveTemplateSource.isTemplateSourceLoading = (name) =>
+  getDefaultResolver().isTemplateSourceLoading(name);
+
+resolveTemplateSource.whenTemplateSourceLoaded = (name) =>
+  getDefaultResolver().whenTemplateSourceLoaded(name);

package/src/storybook/twig/setup.js

@@ -0,0 +1,39 @@
+/**
+ * @file Twig runtime setup for Emulsify's Storybook integration.
+ */
+
+import { registerTwigExtensions } from '../../extensions/twig/index.js';
+import twigInclude from './include.js';
+import twigSource from './source.js';
+
+/**
+ * Configures and extends a standard Twig object for Storybook.
+ *
+ * Emulsify's Twig helpers are platform-agnostic. Platform adapters can pass
+ * optional Twig extension functions when a project needs CMS-specific behavior.
+ *
+ * @param {Object} twig - Twig object that should be configured and extended.
+ * @param {{ extensions?: Function[] }} [options={}] - Optional platform extensions.
+ * @returns {Object} Configured Twig object.
+ */
+export function setupTwig(twig, options = {}) {
+  const extensions = Array.isArray(options.extensions)
+    ? options.extensions
+    : [];
+
+  twig.cache();
+  registerTwigExtensions(twig);
+  twigInclude(twig);
+  twigSource(twig);
+
+  for (const extension of extensions) {
+    if (typeof extension === 'function') {
+      extension(twig);
+    }
+  }
+
+  return twig;
+}
+
+export { default as twigInclude } from './include.js';
+export { default as twigSource } from './source.js';

package/src/storybook/twig/source-events.js

@@ -0,0 +1,5 @@
+/**
+ * @file Shared events for lazy Twig source loading.
+ */
+
+export const TWIG_SOURCE_LOADED_EVENT = 'emulsify:twig-source-loaded';

package/src/storybook/twig/source-extensions.js

@@ -0,0 +1,24 @@
+/**
+ * @file Shared file extension sets for Twig source() handling.
+ */
+
+// Text assets can be safely inlined; binary assets should remain URL-based.
+export const INLINE_ASSET_EXTS = new Set([
+  'svg',
+  'html',
+  'twig',
+  'css',
+  'js',
+  'json',
+  'txt',
+  'md',
+]);
+
+export const IMAGE_ASSET_EXTS = new Set([
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'webp',
+  'avif',
+]);