@emulsify/core 3.5.0 → 4.0.0

package/src/extensions/twig/functions/bem.js

@@ -0,0 +1,166 @@
+/**
+ * @file Native `bem()` Twig function implementation.
+ * @module extensions/twig/functions/bem
+ */
+
+import {
+  AttributeBag,
+  attributesFromContext,
+  clearContextAttributes,
+} from '../../shared/attributes.js';
+import { flattenList } from '../../shared/lists.js';
+import { isPlainObject } from '../../shared/object.js';
+
+/**
+ * Normalize positional and object-style BEM arguments into one shape.
+ *
+ * @param {string|Object} baseClass - Base class or options object.
+ * @param {*[]} modifiers - Positional modifiers.
+ * @param {string} blockname - Positional block name.
+ * @param {*[]} extra - Positional extra classes.
+ * @param {Object} attributes - Positional extra attributes.
+ * @returns {{
+ *   baseClass: *,
+ *   modifiers: *,
+ *   blockname: *,
+ *   extra: *,
+ *   attributes: Object
+ * }} Normalized BEM options.
+ */
+function normalizeBemOptions(
+  baseClass,
+  modifiers,
+  blockname,
+  extra,
+  attributes,
+) {
+  if (!isPlainObject(baseClass)) {
+    return {
+      baseClass,
+      modifiers,
+      blockname,
+      extra,
+      attributes,
+    };
+  }
+
+  const options = baseClass;
+  const hasBEMObjectShape = options.block && options.element;
+
+  // Prefer explicit keys, then map block/element object syntax.
+  return {
+    baseClass:
+      options.baseClass ||
+      options.base_class ||
+      options.base ||
+      (hasBEMObjectShape ? options.element : options.block),
+    modifiers: options.modifiers || [],
+    blockname:
+      options.blockname ||
+      options.blockName ||
+      (hasBEMObjectShape ? options.block : options.element) ||
+      '',
+    extra: options.extra || [],
+    attributes: options.attributes || {},
+  };
+}
+
+/**
+ * Convert an argument into a clean list while preserving string contents.
+ *
+ * Class-token sanitization happens later in AttributeBag so BEM composition can
+ * treat classes and attributes through one path.
+ *
+ * @param {*} value - Value to normalize.
+ * @returns {*[]} Flattened non-empty values.
+ */
+function normalizeList(value) {
+  return flattenList(value).filter((item) => {
+    return item !== null && typeof item !== 'undefined' && item !== '';
+  });
+}
+
+/**
+ * Build BEM attributes.
+ *
+ * @param {string|Object} baseClass - Base class or object-style options.
+ * @param {*[]} [modifiers=[]] - Modifier values.
+ * @param {string} [blockname=''] - Block name for element output.
+ * @param {*[]} [extra=[]] - Non-BEM class values.
+ * @param {Object} [attributes={}] - Additional attributes.
+ * @param {Object} [invocationContext] - Twig.js function invocation `this`.
+ * @returns {AttributeBag} AttributeBag ready for Twig serialization.
+ */
+export function bemAttributes(
+  baseClass,
+  modifiers = [],
+  blockname = '',
+  extra = [],
+  attributes = {},
+  invocationContext,
+) {
+  const options = normalizeBemOptions(
+    baseClass,
+    modifiers,
+    blockname,
+    extra,
+    attributes,
+  );
+  const normalizedBaseClass = String(options.baseClass || '').trim();
+  const normalizedBlockname = String(options.blockname || '').trim();
+  const classes = [];
+
+  // Generate canonical BEM class names before adding non-BEM extras.
+  if (normalizedBaseClass) {
+    const classPrefix = normalizedBlockname
+      ? `${normalizedBlockname}__${normalizedBaseClass}`
+      : normalizedBaseClass;
+
+    classes.push(classPrefix);
+
+    for (const modifier of normalizeList(options.modifiers)) {
+      classes.push(`${classPrefix}--${modifier}`);
+    }
+  }
+
+  classes.push(...normalizeList(options.extra));
+
+  const attributeBag = new AttributeBag(options.attributes);
+  attributeBag.addClass(classes);
+
+  // Merge then clear context attributes to match Drupal's print-once model.
+  if (invocationContext?.context?.attributes) {
+    const contextAttributes = attributesFromContext(invocationContext);
+    attributeBag.merge(contextAttributes);
+    clearContextAttributes(invocationContext);
+  }
+
+  return attributeBag;
+}
+
+/**
+ * Twig.js adapter for `bem()`.
+ *
+ * @param {string|Object} baseClass - Base class or object-style options.
+ * @param {*[]} modifiers - Modifier values.
+ * @param {string} blockname - Block name for element output.
+ * @param {*[]} extra - Non-BEM class values.
+ * @param {Object} attributes - Additional attributes.
+ * @returns {AttributeBag} AttributeBag ready for Twig serialization.
+ */
+export function bemTwigFunction(
+  baseClass,
+  modifiers,
+  blockname,
+  extra,
+  attributes,
+) {
+  return bemAttributes(
+    baseClass,
+    modifiers,
+    blockname,
+    extra,
+    attributes,
+    this,
+  );
+}

package/src/extensions/twig/index.js

@@ -0,0 +1,13 @@
+/**
+ * @file Public exports for native Twig extensions.
+ * @module extensions/twig
+ */
+
+// Export registry helpers before individual functions for the public API.
+export { getTwigFunctionMap } from './function-map.js';
+export { registerTwigExtensions } from './register.js';
+export {
+  addAttributes,
+  addAttributesTwigFunction,
+} from './functions/add-attributes.js';
+export { bemAttributes, bemTwigFunction } from './functions/bem.js';

package/src/extensions/twig/register.js

@@ -0,0 +1,52 @@
+/**
+ * @file Twig.js extension registration entry point.
+ * @module extensions/twig/register
+ */
+
+import { getTwigFunctionMap } from './function-map.js';
+import { getTwigTagDefinitions } from './tag-map.js';
+
+/**
+ * Twig instances that have already received native Emulsify extensions.
+ *
+ * @type {WeakSet<Object>}
+ */
+const registeredTwigInstances = new WeakSet();
+
+/**
+ * Register native Emulsify Twig functions and logic tags with Twig.js.
+ *
+ * @param {Object} Twig - Twig.js module or compatible extension target.
+ * @returns {Object} The same Twig instance after registration.
+ * @throws {TypeError} When the provided value cannot register Twig extensions.
+ */
+export function registerTwigExtensions(Twig) {
+  if (
+    !Twig ||
+    typeof Twig.extendFunction !== 'function' ||
+    typeof Twig.extendTag !== 'function' ||
+    typeof Twig.extend !== 'function'
+  ) {
+    throw new TypeError(
+      'A Twig.js instance with extendFunction(), extendTag(), and extend() is required.',
+    );
+  }
+
+  if (registeredTwigInstances.has(Twig)) {
+    return Twig;
+  }
+
+  // Register once so repeated Storybook/Vite setup calls stay idempotent.
+  for (const [name, definition] of Object.entries(getTwigFunctionMap())) {
+    Twig.extendFunction(name, definition);
+  }
+
+  Twig.extend((InternalTwig) => {
+    for (const definition of getTwigTagDefinitions(InternalTwig)) {
+      Twig.extendTag(definition);
+    }
+  });
+
+  registeredTwigInstances.add(Twig);
+  return Twig;
+}

package/src/extensions/twig/tag-map.js

@@ -0,0 +1,16 @@
+/**
+ * @file Native Twig logic tag definitions.
+ * @module extensions/twig/tag-map
+ */
+
+import { getSwitchTagDefinitions } from './tags/switch.js';
+
+/**
+ * Get Twig.js logic tag definitions for native Emulsify helpers.
+ *
+ * @param {Object} Twig - Twig.js module or compatible extension target.
+ * @returns {Object[]} Logic tag definitions for Twig.extendTag().
+ */
+export function getTwigTagDefinitions(Twig) {
+  return [...getSwitchTagDefinitions(Twig)];
+}

package/src/extensions/twig/tags/switch.js

@@ -0,0 +1,266 @@
+/**
+ * @file Native Twig.js switch/case/default logic tags.
+ * @module extensions/twig/tags/switch
+ */
+
+const SWITCH_TAG_TYPE = 'emulsify_switch';
+const CASE_TAG_TYPE = 'emulsify_case';
+const DEFAULT_TAG_TYPE = 'emulsify_default';
+const ENDSWITCH_TAG_TYPE = 'emulsify_endswitch';
+const DOUBLE_QUOTE = '"';
+const SINGLE_QUOTE = '\u0027';
+
+const OPENING_BRACKETS = new Set(['(', '[', '{']);
+const CLOSING_BRACKETS = new Set([')', ']', '}']);
+
+/**
+ * Determine whether a character can be part of a Twig identifier.
+ *
+ * @param {string} [character] - Character to inspect.
+ * @returns {boolean} TRUE when the character is identifier-like.
+ */
+function isIdentifierCharacter(character) {
+  return Boolean(character && /[A-Za-z0-9_]/.test(character));
+}
+
+/**
+ * Split a case expression on top-level Twig `or` operators.
+ *
+ * Emulsify Tools uses `or` to express multiple PHP switch case values. Twig.js
+ * receives the full tag body as a string, so split only when `or` appears
+ * outside quotes and nested expressions.
+ *
+ * @param {string} expression - Raw `{% case ... %}` expression.
+ * @returns {string[]} One or more Twig expressions to compile as case values.
+ */
+export function splitSwitchCaseExpressions(expression) {
+  const parts = [];
+  let quote = null;
+  let escaped = false;
+  let depth = 0;
+  let start = 0;
+
+  for (let index = 0; index < expression.length; index++) {
+    const character = expression.charAt(index);
+
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+
+      if (character === '\\') {
+        escaped = true;
+        continue;
+      }
+
+      if (character === quote) {
+        quote = null;
+      }
+
+      continue;
+    }
+
+    if (character === DOUBLE_QUOTE || character === SINGLE_QUOTE) {
+      quote = character;
+      continue;
+    }
+
+    if (OPENING_BRACKETS.has(character)) {
+      depth += 1;
+      continue;
+    }
+
+    if (CLOSING_BRACKETS.has(character)) {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+
+    if (
+      depth === 0 &&
+      expression.slice(index, index + 2) === 'or' &&
+      !isIdentifierCharacter(expression.charAt(index - 1)) &&
+      !isIdentifierCharacter(expression.charAt(index + 2))
+    ) {
+      const part = expression.slice(start, index).trim();
+      if (part) {
+        parts.push(part);
+      }
+      start = index + 2;
+      index += 1;
+    }
+  }
+
+  const tail = expression.slice(start).trim();
+  if (tail) {
+    parts.push(tail);
+  }
+
+  return parts;
+}
+
+/**
+ * Compile a Twig expression into a stack Twig.js can parse later.
+ *
+ * @param {Object} Twig - Twig.js module.
+ * @param {Object} state - Twig.js compile state.
+ * @param {string} value - Twig expression source.
+ * @returns {Object[]} Compiled expression stack.
+ */
+function compileExpression(Twig, state, value) {
+  return Twig.expression.compile.call(state, {
+    type: Twig.expression.type.expression,
+    value,
+  }).stack;
+}
+
+/**
+ * Determine whether the current Twig logic chain belongs to an Emulsify switch.
+ *
+ * @param {*} chain - Twig.js logic chain value.
+ * @returns {boolean} TRUE when the chain was opened by `{% switch %}`.
+ */
+function isSwitchChain(chain) {
+  return Boolean(chain && chain.emulsifySwitch);
+}
+
+/**
+ * Compare switch values using PHP-style loose switch semantics.
+ *
+ * @param {*} switchValue - Evaluated `{% switch ... %}` value.
+ * @param {*} caseValue - Evaluated `{% case ... %}` value.
+ * @returns {boolean} TRUE when the case matches.
+ */
+function isSwitchMatch(switchValue, caseValue) {
+  // PHP switch statements use loose equality; mirror that for Drupal parity.
+  return switchValue == caseValue;
+}
+
+/**
+ * Render a token body and preserve the current switch chain.
+ *
+ * @param {Object} Twig - Twig.js module.
+ * @param {Object} state - Twig.js parse state.
+ * @param {Object} token - Compiled Twig.js logic token.
+ * @param {Object} context - Twig render context.
+ * @param {Object} chain - Active switch chain.
+ * @returns {Object|Promise<Object>} Twig.js logic parse result.
+ */
+function renderSwitchBranch(Twig, state, token, context, chain) {
+  return state.parseAsync(token.output || [], context).then((output) => ({
+    chain,
+    output,
+  }));
+}
+
+/**
+ * Create Twig.js logic tag definitions for switch/case/default/endswitch.
+ *
+ * @param {Object} Twig - Twig.js module or compatible extension target.
+ * @returns {Object[]} Logic tag definitions.
+ */
+export function getSwitchTagDefinitions(Twig) {
+  return [
+    {
+      type: SWITCH_TAG_TYPE,
+      regex: /^switch\s+([\s\S]+)$/,
+      next: [CASE_TAG_TYPE, DEFAULT_TAG_TYPE, ENDSWITCH_TAG_TYPE],
+      open: true,
+      compile(token) {
+        token.stack = compileExpression(Twig, this, token.match[1]);
+        delete token.match;
+        return token;
+      },
+      parse(token, context) {
+        const state = this;
+
+        return Twig.expression.parseAsync
+          .call(state, token.stack, context)
+          .then((value) => ({
+            chain: {
+              emulsifySwitch: true,
+              matched: false,
+              value,
+            },
+            output: '',
+          }));
+      },
+    },
+    {
+      type: CASE_TAG_TYPE,
+      regex: /^case\s+([\s\S]+)$/,
+      next: [CASE_TAG_TYPE, DEFAULT_TAG_TYPE, ENDSWITCH_TAG_TYPE],
+      open: false,
+      compile(token) {
+        token.stacks = splitSwitchCaseExpressions(token.match[1]).map(
+          (expression) => compileExpression(Twig, this, expression),
+        );
+        delete token.match;
+        return token;
+      },
+      parse(token, context, chain) {
+        const state = this;
+
+        if (!isSwitchChain(chain)) {
+          throw new Twig.Error('{% case %} must be used inside {% switch %}.');
+        }
+
+        if (chain.matched) {
+          return {
+            chain,
+            output: '',
+          };
+        }
+
+        return Twig.Promise.all(
+          token.stacks.map((stack) =>
+            Twig.expression.parseAsync.call(state, stack, context),
+          ),
+        ).then((values) => {
+          if (
+            !values.some((caseValue) => isSwitchMatch(chain.value, caseValue))
+          ) {
+            return {
+              chain,
+              output: '',
+            };
+          }
+
+          chain.matched = true;
+          return renderSwitchBranch(Twig, state, token, context, chain);
+        });
+      },
+    },
+    {
+      type: DEFAULT_TAG_TYPE,
+      regex: /^default$/,
+      next: [ENDSWITCH_TAG_TYPE],
+      open: false,
+      parse(token, context, chain) {
+        const state = this;
+
+        if (!isSwitchChain(chain)) {
+          throw new Twig.Error(
+            '{% default %} must be used inside {% switch %}.',
+          );
+        }
+
+        if (chain.matched) {
+          return {
+            chain,
+            output: '',
+          };
+        }
+
+        chain.matched = true;
+        return renderSwitchBranch(Twig, state, token, context, chain);
+      },
+    },
+    {
+      type: ENDSWITCH_TAG_TYPE,
+      regex: /^endswitch$/,
+      next: [],
+      open: false,
+    },
+  ];
+}

package/src/storybook/index.js

@@ -0,0 +1,14 @@
+/**
+ * @file Public Storybook helpers for Emulsify Core.
+ * @module storybook
+ */
+
+export {
+  getActiveStorybookAdapter,
+  renderHtmlStoryResult,
+  renderTwig,
+  renderTwigHtml,
+  renderTwigToHtml,
+  TwigHtmlStory,
+  TwigStory,
+} from './render-twig.js';

package/src/storybook/main-config.js

@@ -0,0 +1,132 @@
+/**
+ * @file Helpers for applying project Storybook main configuration overrides.
+ */
+
+/**
+ * Identify a Storybook addon so project config can override default addon
+ * options without duplicating the addon in the final list.
+ *
+ * @param {string|{name?: string}} addon - Storybook addon entry.
+ * @returns {string|null} Stable addon key when available.
+ */
+function addonKey(addon) {
+  if (typeof addon === 'string') return addon;
+  if (addon && typeof addon.name === 'string') return addon.name;
+  return null;
+}
+
+/**
+ * Merge Storybook addon lists while preserving default addon order.
+ *
+ * Project addons are appended by default. When a project provides an addon with
+ * the same package name as a default addon, its entry replaces the default so
+ * projects can configure default addons without creating duplicates.
+ *
+ * @param {Array<string|object>} defaults - Emulsify Core default addons.
+ * @param {Array<string|object>} overrides - Project-provided addons.
+ * @param {{ replace?: boolean }} [options] - Whether overrides replace defaults.
+ * @returns {Array<string|object>} Final addon list.
+ */
+export function mergeStorybookAddons(
+  defaults = [],
+  overrides = [],
+  { replace = false } = {},
+) {
+  if (replace) return [...overrides];
+
+  const merged = [...defaults];
+  const indexesByKey = new Map();
+
+  merged.forEach((addon, index) => {
+    const key = addonKey(addon);
+    if (key) indexesByKey.set(key, index);
+  });
+
+  for (const addon of overrides) {
+    const key = addonKey(addon);
+    const existingIndex = key ? indexesByKey.get(key) : undefined;
+    if (existingIndex !== undefined) {
+      merged.splice(existingIndex, 1, addon);
+      continue;
+    }
+
+    if (key) indexesByKey.set(key, merged.length);
+    merged.push(addon);
+  }
+
+  return merged;
+}
+
+/**
+ * Normalize an optional project `config/emulsify-core/storybook/main.js` module.
+ *
+ * @param {object} [module] - ESM module namespace loaded from the project.
+ * @returns {{ config: object|Function, extendConfig?: Function, replaceAddons: boolean }}
+ * Normalized override details.
+ */
+export function normalizeStorybookConfigOverrideModule(module = {}) {
+  const config = module.default || {};
+
+  return {
+    config,
+    extendConfig:
+      typeof module.extendConfig === 'function'
+        ? module.extendConfig
+        : undefined,
+    replaceAddons: module.replaceAddons === true,
+  };
+}
+
+/**
+ * Apply project Storybook main config overrides to Emulsify's default config.
+ *
+ * Default-exported override objects are shallow-merged, except `addons`, which
+ * are appended by default. Export `replaceAddons = true` or include
+ * `replaceAddons: true` in the default config object when full replacement is
+ * needed. Named `extendConfig()` runs last for advanced cases.
+ *
+ * @param {object} baseConfig - Emulsify Core Storybook config.
+ * @param {{ config?: object|Function, extendConfig?: Function, replaceAddons?: boolean }} [overrides]
+ * Project override details.
+ * @param {object} [context] - Context passed to config factories.
+ * @returns {Promise<object>} Final Storybook config.
+ */
+export async function applyStorybookConfigOverrides(
+  baseConfig,
+  overrides = {},
+  context = {},
+) {
+  const rawConfig =
+    typeof overrides.config === 'function'
+      ? await overrides.config(context)
+      : overrides.config;
+  const plainConfig =
+    rawConfig && typeof rawConfig === 'object' ? { ...rawConfig } : {};
+  const configReplaceAddons = plainConfig.replaceAddons === true;
+  delete plainConfig.replaceAddons;
+  delete plainConfig.extendConfig;
+  const replaceAddons = overrides.replaceAddons || configReplaceAddons === true;
+
+  let merged = {
+    ...baseConfig,
+    ...plainConfig,
+  };
+
+  if (Array.isArray(plainConfig.addons)) {
+    merged = {
+      ...merged,
+      addons: mergeStorybookAddons(baseConfig.addons, plainConfig.addons, {
+        replace: replaceAddons,
+      }),
+    };
+  }
+
+  if (typeof overrides.extendConfig === 'function') {
+    const extended = await overrides.extendConfig(merged, context);
+    if (extended && typeof extended === 'object') {
+      merged = extended;
+    }
+  }
+
+  return merged;
+}