@emulsify/core 3.4.1 → 4.0.0

package/scripts/check-node-version.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * @file Enforces the supported Node.js floor for project scripts.
+ */
+
+const REQUIRED_NODE_MAJOR = 24;
+const [currentNodeMajor] = process.versions.node.split('.').map(Number);
+
+if (currentNodeMajor < REQUIRED_NODE_MAJOR) {
+  // Fail before npm scripts run with an unsupported runtime.
+  console.error(
+    `Emulsify Core requires Node.js ${REQUIRED_NODE_MAJOR} or later. ` +
+      `Current version: ${process.versions.node}. Run nvm use or install Node.js 24+.`,
+  );
+  process.exit(1);
+}
+
+// Keep successful checks quiet so script output belongs to the called command.

package/scripts/loadYaml.js

@@ -1,7 +1,10 @@
+/**
+ * @file YAML fixture loader used by tests and small utility scripts.
+ */
+
 import { resolve } from 'path';
 import { readFileSync } from 'fs';
 import { parse } from 'yaml';
-import R from 'ramda';
 
 /**
  * Small utility function that loads a yaml file and parses it synchronously.
@@ -12,6 +15,7 @@ import R from 'ramda';
  * @returns {string} JavaScript object that results from the yaml parsing of the specified file.
  */
 export default function loadYaml(relativePath) {
+  // Resolve from this script directory so tests can pass stable relative paths.
   const fullPath = resolve(__dirname, relativePath);
   return parse(readFileSync(fullPath, 'utf8'));
 }

package/src/extensions/index.js

@@ -0,0 +1,8 @@
+/**
+ * @file Public extension namespace exports.
+ * @module extensions
+ */
+
+// Keep extension families namespaced so new runtimes can be added safely.
+export * as react from './react/index.js';
+export * as twig from './twig/index.js';

package/src/extensions/react/index.js

@@ -0,0 +1,12 @@
+/**
+ * @file Public exports for React extension helpers.
+ * @module extensions/react
+ * @reserved React extension registry behavior is not yet implemented. See
+ * `register.js` for the current no-op contract.
+ */
+
+// Re-export from a single entry point for consumers and future registry growth.
+export {
+  createReactExtensionRegistry,
+  defineReactExtension,
+} from './register.js';

package/src/extensions/react/register.js

@@ -0,0 +1,45 @@
+/**
+ * @file React extension registry placeholders.
+ * @module extensions/react/register
+ */
+
+/**
+ * Return the provided React extension definition unchanged.
+ *
+ * @reserved Registry behavior is not yet implemented and may change in a
+ * future minor release.
+ * @example
+ * const extension = defineReactExtension({
+ *   name: 'project-react-components',
+ *   components: {},
+ * });
+ * // Safe today: use `extension` directly instead of relying on registry side
+ * // effects.
+ *
+ * @param {Object} extension - React extension definition.
+ * @returns {Object} The provided extension definition.
+ */
+export function defineReactExtension(extension) {
+  // Keep this pass-through stable until React extensions need normalization.
+  return extension;
+}
+
+/**
+ * Return React extension definitions after filtering falsy values.
+ *
+ * @reserved Registry behavior is not yet implemented and may change in a
+ * future minor release.
+ * @example
+ * const registry = createReactExtensionRegistry([
+ *   maybeExtension && defineReactExtension(maybeExtension),
+ * ]);
+ * // Safe today: read from `registry` directly instead of relying on runtime
+ * // registration.
+ *
+ * @param {Object[]} [extensions=[]] - Candidate extension definitions.
+ * @returns {Object[]} Filtered extension definitions.
+ */
+export function createReactExtensionRegistry(extensions = []) {
+  // Drop empty placeholders so callers can compose optional extension arrays.
+  return extensions.filter(Boolean);
+}

package/src/extensions/shared/attributes.js

@@ -0,0 +1,308 @@
+/**
+ * @file Attribute serialization and composition utilities.
+ * @module extensions/shared/attributes
+ */
+
+import { escapeAttributeValue, isSafeAttributeName } from './html.js';
+import { flattenList, uniqueList } from './lists.js';
+import { isPlainObject } from './object.js';
+
+/**
+ * Cache cleaned class tokens because BEM class names repeat heavily across
+ * component renders during Storybook sessions.
+ *
+ * @type {Map<string, string>}
+ */
+const classNameCache = new Map();
+
+/**
+ * Brand AttributeBag instances without exposing a mutable marker property on
+ * the rendered object.
+ *
+ * @type {WeakSet<AttributeBag>}
+ */
+const attributeBags = new WeakSet();
+
+/**
+ * Clean a single value into a CSS class token compatible with Twig.js output.
+ *
+ * @param {*} value - Candidate class token.
+ * @returns {string} Cleaned class token or an empty string.
+ */
+function cleanClassToken(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+
+  // Cache by raw input so repeated BEM renders avoid repeated regex work.
+  if (classNameCache.has(raw)) {
+    return classNameCache.get(raw);
+  }
+
+  const cleaned = raw
+    .replace(/[^_a-zA-Z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/^([0-9])/, '_$1');
+
+  classNameCache.set(raw, cleaned);
+  return cleaned;
+}
+
+/**
+ * Convert scalar, array, or AttributeBag values into clean class tokens.
+ *
+ * @param {*} value - Value containing one or more class names.
+ * @returns {string[]} Clean, unique class tokens.
+ */
+export function classTokensFromValue(value) {
+  if (isAttributeBag(value)) {
+    // AttributeBag class values are already normalized by this module.
+    return value.getClassList();
+  }
+
+  return uniqueList(
+    flattenList(value)
+      .flatMap((item) => String(item || '').split(/\s+/))
+      .map((item) => cleanClassToken(item))
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Normalize non-class attribute values into serializable pieces.
+ *
+ * @param {*} value - Value to normalize.
+ * @returns {string|string[]|boolean|Object|null} Serializable value or null.
+ */
+function valueToAttributeParts(value) {
+  if (isAttributeBag(value)) {
+    // Preserve nested AttributeBag composition for helpers like add_attributes().
+    return value.toObject();
+  }
+
+  if (value === null || typeof value === 'undefined' || value === false) {
+    return null;
+  }
+
+  if (Array.isArray(value)) {
+    return flattenList(value)
+      .filter((item) => item !== null && typeof item !== 'undefined')
+      .map((item) => String(item));
+  }
+
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  if (typeof value === 'number' || typeof value === 'string') {
+    return String(value);
+  }
+
+  if (
+    typeof value?.toString === 'function' &&
+    value.toString !== Object.prototype.toString
+  ) {
+    return String(value);
+  }
+
+  return null;
+}
+
+/**
+ * Extract class tokens from legacy `class="..."` strings.
+ *
+ * This keeps compatibility with old `bem()` string output without treating
+ * arbitrary `key=value` strings as trusted markup.
+ *
+ * @param {*} value - Potential legacy class attribute string.
+ * @returns {string|null} Raw class value when the string is class-only.
+ */
+function parseClassAttributeString(value) {
+  const match = String(value || '').match(/^class=(["'])(.*?)\1$/);
+  return match ? match[2] : null;
+}
+
+/**
+ * Determine whether a value is an AttributeBag instance.
+ *
+ * @param {*} value - Value to inspect.
+ * @returns {boolean} TRUE when the value is branded by this module.
+ */
+export function isAttributeBag(value) {
+  return Boolean(
+    value && typeof value === 'object' && attributeBags.has(value),
+  );
+}
+
+/**
+ * Mutable HTML attribute collection with safe serialization.
+ *
+ * The class mirrors the tiny subset of Drupal's Attribute object needed by
+ * Storybook and Vite-rendered Twig templates.
+ */
+export class AttributeBag {
+  /**
+   * Create an attribute collection.
+   *
+   * @param {Object} [initialAttributes={}] - Initial attributes to merge.
+   */
+  constructor(initialAttributes = {}) {
+    attributeBags.add(this);
+    this.attributes = new Map();
+
+    this.merge(initialAttributes);
+  }
+
+  /**
+   * Create a copy of this collection.
+   *
+   * @returns {AttributeBag} New AttributeBag with equivalent attributes.
+   */
+  clone() {
+    return new AttributeBag(this.toObject());
+  }
+
+  /**
+   * Get the normalized class list.
+   *
+   * @returns {string[]} Current class tokens.
+   */
+  getClassList() {
+    return this.attributes.get('class') || [];
+  }
+
+  /**
+   * Append one or more class tokens.
+   *
+   * @param {*} value - Class value to normalize and append.
+   * @returns {AttributeBag} Current instance for chaining.
+   */
+  addClass(value) {
+    const tokens = classTokensFromValue(value);
+    if (!tokens.length) return this;
+
+    const existing = this.attributes.get('class') || [];
+    this.attributes.set('class', uniqueList([...existing, ...tokens]));
+    return this;
+  }
+
+  /**
+   * Set or merge an attribute.
+   *
+   * Class values are always merged. Other attributes replace existing values
+   * once they have been normalized and validated.
+   *
+   * @param {string} name - Attribute name.
+   * @param {*} value - Attribute value.
+   * @returns {AttributeBag} Current instance for chaining.
+   */
+  set(name, value) {
+    const attributeName = String(name || '').trim();
+    if (!isSafeAttributeName(attributeName)) return this;
+
+    if (attributeName === 'class') {
+      // Legacy callers may still pass class="..." strings from old helpers.
+      const classString =
+        typeof value === 'string' ? parseClassAttributeString(value) : null;
+      this.addClass(classString || value);
+      return this;
+    }
+
+    const normalizedValue = valueToAttributeParts(value);
+    if (normalizedValue === null) return this;
+
+    this.attributes.set(attributeName, normalizedValue);
+    return this;
+  }
+
+  /**
+   * Merge an object or another AttributeBag into this collection.
+   *
+   * @param {Object|AttributeBag} value - Attribute source.
+   * @returns {AttributeBag} Current instance for chaining.
+   */
+  merge(value) {
+    if (!value) return this;
+
+    if (isAttributeBag(value)) {
+      for (const [name, attributeValue] of value.attributes.entries()) {
+        this.set(name, attributeValue);
+      }
+      return this;
+    }
+
+    if (!isPlainObject(value)) {
+      return this;
+    }
+
+    for (const [name, attributeValue] of Object.entries(value)) {
+      if (name === '_keys') continue;
+      this.set(name, attributeValue);
+    }
+
+    return this;
+  }
+
+  /**
+   * Convert attributes to a plain object.
+   *
+   * @returns {Object} Plain attribute map.
+   */
+  toObject() {
+    return Object.fromEntries(this.attributes.entries());
+  }
+
+  /**
+   * Serialize the attribute collection for direct Twig output.
+   *
+   * @returns {string} HTML-safe attribute string.
+   */
+  toString() {
+    return Array.from(this.attributes.entries())
+      .map(([name, value]) => {
+        if (name === 'class' && Array.isArray(value)) {
+          if (!value.length) return '';
+          return `class="${escapeAttributeValue(value.join(' '))}"`;
+        }
+
+        if (value === true) {
+          return name;
+        }
+
+        if (Array.isArray(value)) {
+          return `${name}="${escapeAttributeValue(value.join(' '))}"`;
+        }
+
+        return `${name}="${escapeAttributeValue(value)}"`;
+      })
+      .filter(Boolean)
+      .join(' ');
+  }
+}
+
+/**
+ * Build an AttributeBag from the current Twig invocation context.
+ *
+ * @param {Object} invocationContext - Twig.js function invocation `this`.
+ * @returns {AttributeBag} Attribute collection from context attributes.
+ */
+export function attributesFromContext(invocationContext) {
+  return new AttributeBag(invocationContext?.context?.attributes || {});
+}
+
+/**
+ * Clear context attributes after they have been consumed.
+ *
+ * Drupal removes attributes after printing them so they do not leak into child
+ * includes; this mirrors that behavior for Storybook and Vite rendering.
+ *
+ * @param {Object} invocationContext - Twig.js function invocation `this`.
+ * @returns {void}
+ */
+export function clearContextAttributes(invocationContext) {
+  if (
+    invocationContext?.context &&
+    Object.hasOwn(invocationContext.context, 'attributes')
+  ) {
+    invocationContext.context.attributes = {};
+  }
+}

package/src/extensions/shared/html.js

@@ -0,0 +1,41 @@
+/**
+ * @file HTML escaping and attribute-name validation helpers.
+ * @module extensions/shared/html
+ */
+
+const ATTRIBUTE_NAME_PATTERN = /^[A-Za-z_:][A-Za-z0-9:_.-]*$/;
+
+/**
+ * Determine whether a name is safe to print as an HTML attribute name.
+ *
+ * @param {string} name - Candidate attribute name.
+ * @returns {boolean} TRUE when the name can be safely serialized.
+ */
+export function isSafeAttributeName(name) {
+  // Reject spaces, quotes, and event-like malformed names before serialization.
+  return ATTRIBUTE_NAME_PATTERN.test(String(name || ''));
+}
+
+/**
+ * Escape a value for use inside a double-quoted HTML attribute.
+ *
+ * @param {*} value - Attribute value to serialize.
+ * @returns {string} Escaped value.
+ */
+export function escapeAttributeValue(value) {
+  return String(value).replace(/[&"<>]/g, (character) => {
+    // Return the named entity for each unsafe character.
+    switch (character) {
+      case '&':
+        return '&amp;';
+      case '"':
+        return '&quot;';
+      case '<':
+        return '&lt;';
+      case '>':
+        return '&gt;';
+      default:
+        return character;
+    }
+  });
+}

package/src/extensions/shared/lists.js

@@ -0,0 +1,38 @@
+/**
+ * @file List coercion utilities shared by extension implementations.
+ * @module extensions/shared/lists
+ */
+
+import { unique } from '../../../config/vite/utils/unique.js';
+
+export { unique };
+
+/**
+ * Convert scalar or nested array values into a flat list.
+ *
+ * @param {*} value - Value to flatten.
+ * @returns {*[]} Flat list with null, undefined, and false treated as empty.
+ */
+export function flattenList(value) {
+  if (value === null || typeof value === 'undefined' || value === false) {
+    // Match Twig-style falsey class handling without discarding 0 or ''.
+    return [];
+  }
+
+  if (!Array.isArray(value)) {
+    return [value];
+  }
+
+  return value.flatMap((item) => flattenList(item));
+}
+
+/**
+ * Return values in their first-seen order with duplicates removed.
+ *
+ * @param {*[]} values - Values to deduplicate.
+ * @returns {*[]} Unique values.
+ */
+export function uniqueList(values) {
+  // Preserve first-seen order; class order can affect utility CSS output.
+  return unique(values);
+}

package/src/extensions/shared/object.js

@@ -0,0 +1,22 @@
+/**
+ * @file Object type guards shared by extension implementations.
+ * @module extensions/shared/object
+ */
+
+/**
+ * Determine whether a value is a plain object.
+ *
+ * Objects from Twig.js context data generally have either Object.prototype or
+ * a null prototype. Class instances are intentionally excluded so extension
+ * code does not accidentally treat rich objects as attribute maps.
+ *
+ * @param {*} value - Value to inspect.
+ * @returns {boolean} TRUE when the value is a plain object.
+ */
+export function isPlainObject(value) {
+  if (!value || typeof value !== 'object') return false;
+
+  // Twig context maps may be created with null prototypes.
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @file Native Twig function map.
+ * @module extensions/twig/function-map
+ */
+
+import { addAttributesTwigFunction } from './functions/add-attributes.js';
+import { bemTwigFunction } from './functions/bem.js';
+
+/**
+ * Get Twig.js function definitions for native Emulsify helpers.
+ *
+ * @returns {Record<string, Function>} Function names keyed to Twig callbacks.
+ */
+export function getTwigFunctionMap() {
+  // Twig.js expects function names keyed to callable implementations.
+  return {
+    add_attributes: addAttributesTwigFunction,
+    bem: bemTwigFunction,
+  };
+}

package/src/extensions/twig/functions/add-attributes.js

@@ -0,0 +1,39 @@
+/**
+ * @file Native `add_attributes()` Twig function implementation.
+ * @module extensions/twig/functions/add-attributes
+ */
+
+import {
+  AttributeBag,
+  attributesFromContext,
+  clearContextAttributes,
+} from '../../shared/attributes.js';
+
+/**
+ * Merge additional attributes with attributes from the current Twig context.
+ *
+ * @param {Object} [additionalAttributes={}] - Attributes to add or merge.
+ * @param {Object} [invocationContext] - Twig.js function invocation `this`.
+ * @returns {AttributeBag} AttributeBag ready for Twig serialization.
+ */
+export function addAttributes(additionalAttributes = {}, invocationContext) {
+  // Context attributes are merged first so explicit additions can append safely.
+  const attributeBag = attributesFromContext(invocationContext);
+  attributeBag.merge(additionalAttributes);
+  clearContextAttributes(invocationContext);
+
+  return attributeBag;
+}
+
+/**
+ * Twig.js adapter for `add_attributes()`.
+ *
+ * @param {Object} [additionalAttributes={}] - Attributes to add or merge.
+ * @returns {AttributeBag} AttributeBag ready for Twig serialization.
+ */
+export function addAttributesTwigFunction(additionalAttributes = {}) {
+  // Preserve Twig.js' invocation context for Drupal-compatible attributes.
+  return addAttributes(additionalAttributes, this);
+}
+
+export { AttributeBag };