@emulsify/core 3.5.0 → 4.0.1

package/src/storybook/platform-behaviors.js

@@ -0,0 +1,60 @@
+/**
+ * @file Platform-specific Storybook behavior helpers.
+ */
+
+export const genericStorybookAdapter = {
+  loadDrupalBehaviorShim: false,
+  attachDrupalBehaviors: false,
+  registerDrupalTwigFilters: false,
+  loadMirroredComponentCss: false,
+  allowSyncXhrSource: false,
+};
+
+/**
+ * Normalize optional platform adapter flags into the full Storybook shape.
+ *
+ * @param {object} [adapter] - Candidate Storybook adapter flags.
+ * @returns {object} Storybook adapter flags with generic defaults.
+ */
+export function normalizeStorybookPlatformAdapter(adapter = {}) {
+  return {
+    ...genericStorybookAdapter,
+    ...(adapter || {}),
+  };
+}
+
+/**
+ * Attach platform-specific behaviors after a Storybook render.
+ *
+ * Drupal behavior attachment is opt-in through the active platform adapter.
+ * Generic and unknown platforms return without creating Drupal globals.
+ *
+ * @param {object} [options={}] - Attachment options.
+ * @param {object} [options.adapter] - Active Storybook platform adapter.
+ * @param {Promise} [options.behaviorShimReady] - Optional behavior shim import.
+ * @param {HTMLElement|Document} [options.context] - Behavior attachment root.
+ * @param {object} [options.settings] - Behavior settings.
+ * @returns {Promise<boolean>} TRUE when Drupal attachBehaviors ran.
+ */
+export async function attachStorybookBehaviors(options = {}) {
+  const adapter = normalizeStorybookPlatformAdapter(options.adapter);
+  if (!adapter.attachDrupalBehaviors) {
+    return false;
+  }
+
+  await (options.behaviorShimReady || Promise.resolve());
+
+  const browserWindow = globalThis.window;
+  const drupal = browserWindow?.Drupal || globalThis.Drupal;
+  if (typeof drupal?.attachBehaviors !== 'function') {
+    return false;
+  }
+
+  drupal.attachBehaviors(
+    options.context,
+    options.settings ||
+      browserWindow?.drupalSettings ||
+      globalThis.drupalSettings,
+  );
+  return true;
+}

package/src/storybook/preview-parameters.js

@@ -0,0 +1,81 @@
+/**
+ * @file Storybook preview parameter override helpers.
+ */
+
+/**
+ * Determine whether a value is a plain object suitable for recursive merging.
+ *
+ * @param {*} value - Candidate value.
+ * @returns {boolean} TRUE when value is a plain object.
+ */
+function isPlainObject(value) {
+  return (
+    Boolean(value) &&
+    Object.prototype.toString.call(value) === '[object Object]'
+  );
+}
+
+/**
+ * Merge Storybook preview parameters while preserving nested defaults.
+ *
+ * Arrays and non-object values are intentionally replaced by overrides. Plain
+ * objects merge recursively so partial `a11y.config` overrides keep defaults
+ * such as the enabled rule list unless a project explicitly replaces them.
+ *
+ * @param {object} [defaults={}] - Default Storybook parameters.
+ * @param {object} [overrides={}] - Project override parameters.
+ * @returns {object} Merged parameters.
+ */
+export function mergePreviewParameters(defaults = {}, overrides = {}) {
+  const merged = { ...defaults };
+
+  for (const [key, value] of Object.entries(overrides || {})) {
+    if (value === undefined) continue;
+
+    // Storybook parameter keys are intentionally dynamic.
+    // eslint-disable-next-line security/detect-object-injection
+    const current = merged[key];
+    const nextValue =
+      isPlainObject(current) && isPlainObject(value)
+        ? mergePreviewParameters(current, value)
+        : value;
+
+    // Storybook parameter keys are intentionally dynamic.
+    // eslint-disable-next-line security/detect-object-injection
+    merged[key] = nextValue;
+  }
+
+  return merged;
+}
+
+/**
+ * Extract parameter overrides from a Vite-imported project preview module.
+ *
+ * Supports both direct parameter objects:
+ *   export default { layout: 'centered' }
+ *
+ * And Storybook-shaped modules:
+ *   export const parameters = { layout: 'centered' }
+ *   export default { parameters: { layout: 'centered' } }
+ *
+ * @param {object} [module] - Imported preview override module.
+ * @returns {object} Preview parameter overrides.
+ */
+export function normalizePreviewOverrideModule(module = {}) {
+  const defaultExport = module?.default;
+
+  if (isPlainObject(module?.parameters)) {
+    return module.parameters;
+  }
+  if (isPlainObject(defaultExport?.parameters)) {
+    return defaultExport.parameters;
+  }
+  if (isPlainObject(defaultExport)) {
+    return defaultExport;
+  }
+  if (isPlainObject(module)) {
+    return module;
+  }
+
+  return {};
+}

package/src/storybook/render-twig.js

@@ -0,0 +1,295 @@
+/**
+ * @file React Storybook renderer for imported Twig template modules.
+ */
+
+import React, { useEffect, useReducer, useRef } from 'react';
+import {
+  attachStorybookBehaviors,
+  normalizeStorybookPlatformAdapter,
+} from './platform-behaviors.js';
+import { TWIG_SOURCE_LOADED_EVENT } from './twig/source-events.js';
+
+/**
+ * Read the normalized Emulsify environment injected by Storybook's Vite config.
+ *
+ * @returns {object} Injected Emulsify environment, when present.
+ */
+function getInjectedEnvironment() {
+  return globalThis.__EMULSIFY_ENV__ || {};
+}
+
+/**
+ * Normalize either a full platform adapter or the storybook adapter subset.
+ *
+ * @param {object} [adapter] - Candidate platform adapter.
+ * @returns {object} Storybook adapter flags.
+ */
+export function getActiveStorybookAdapter(options = {}) {
+  const adapter =
+    options.platformAdapter || getInjectedEnvironment().platformAdapter;
+  return normalizeStorybookPlatformAdapter(adapter?.storybook || adapter);
+}
+
+/**
+ * Build Twig context from Storybook args and optional static defaults.
+ *
+ * @param {object} [args={}] - Storybook args.
+ * @param {{ context?: object|Function }} [options={}] - Render options.
+ * @param {object} [storyContext={}] - Storybook story context.
+ * @returns {object} Twig render context.
+ */
+function buildTwigContext(args = {}, options = {}, storyContext = {}) {
+  if (typeof options.context === 'function') {
+    return options.context(args, storyContext) || {};
+  }
+
+  return {
+    ...(options.context || {}),
+    ...(args || {}),
+  };
+}
+
+/**
+ * Check whether a string looks like rendered HTML markup.
+ *
+ * This deliberately stays conservative. Plain text story output should remain
+ * plain text, while legacy Twig stories that return markup can be promoted to
+ * React-managed HTML rendering.
+ *
+ * @param {*} value - Candidate story result.
+ * @returns {boolean} TRUE when the value appears to be an HTML string.
+ */
+function isLikelyHtmlString(value) {
+  return (
+    typeof value === 'string' &&
+    /^\s*<(?:!doctype|!--|[a-z][\w:-]*)(?:\s|>|\/)/i.test(value)
+  );
+}
+
+/**
+ * Give Storybook's React element wrapper a useful string representation.
+ *
+ * Some legacy stories include decorators like `(story) => `${story()}``.
+ * Storybook React now passes those decorators a React element, which normally
+ * stringifies to `[object Object]`. This preserves the old behavior for Twig
+ * string stories while leaving the element renderable by React.
+ *
+ * @param {*} result - Candidate React story element.
+ * @param {Function} getStoryResult - Function returning the raw story result.
+ * @returns {*} Original or cloned story result.
+ */
+export function withLegacyStoryToString(result, getStoryResult) {
+  if (!React.isValidElement(result) || typeof getStoryResult !== 'function') {
+    return result;
+  }
+
+  const legacyCompatibleElement = { ...result };
+  Object.defineProperty(legacyCompatibleElement, 'toString', {
+    value: () => {
+      try {
+        const storyResult = getStoryResult();
+        return storyResult == null ? '' : String(storyResult);
+      } catch {
+        return Object.prototype.toString.call(result);
+      }
+    },
+  });
+
+  return legacyCompatibleElement;
+}
+
+/**
+ * Extract legacy Twig HTML from a React story element with a custom toString.
+ *
+ * `withLegacyStoryToString()` marks legacy Storybook results by installing a
+ * custom `toString()`. Reading that value here lets the preview decorator route
+ * legacy Twig strings through `TwigHtmlStory` without invoking the story a
+ * second time.
+ *
+ * @param {*} reactElement - Candidate React story element.
+ * @returns {string|undefined} Legacy HTML string when detected.
+ */
+export function legacyStringFromElement(reactElement) {
+  if (!React.isValidElement(reactElement)) {
+    return undefined;
+  }
+  if (reactElement.toString === Object.prototype.toString) {
+    return undefined;
+  }
+
+  try {
+    const legacyHtml = String(reactElement);
+    if (legacyHtml === '[object Object]') {
+      return undefined;
+    }
+    if (typeof legacyHtml !== 'string') {
+      return undefined;
+    }
+    if (!isLikelyHtmlString(legacyHtml)) {
+      return undefined;
+    }
+    return legacyHtml;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Render an imported Twig module into an HTML string.
+ *
+ * @param {Function} template - Twig render function.
+ * @param {object} [args={}] - Storybook args.
+ * @param {object} [options={}] - Render options.
+ * @param {object} [storyContext={}] - Storybook story context.
+ * @returns {string} Rendered HTML.
+ */
+export function renderTwigToHtml(
+  template,
+  args = {},
+  options = {},
+  storyContext = {},
+) {
+  if (typeof template !== 'function') {
+    return '';
+  }
+
+  try {
+    const renderedHtml = template(
+      buildTwigContext(args, options, storyContext),
+    );
+    return renderedHtml == null ? '' : String(renderedHtml);
+  } catch (error) {
+    return `An error occurred whilst rendering Twig story: ${
+      error?.message || error
+    }`;
+  }
+}
+
+/**
+ * React component that renders an HTML string into a stable wrapper element.
+ *
+ * @param {object} props - Component props.
+ * @param {string} [props.html] - Rendered HTML string.
+ * @param {object} [props.options] - Render options.
+ * @returns {React.ReactElement} React element.
+ */
+export function TwigHtmlStory({ html = '', options = {} }) {
+  const wrapperRef = useRef(null);
+  const adapter = getActiveStorybookAdapter(options);
+  const WrapperElement = options.wrapper || 'div';
+
+  useEffect(() => {
+    void attachStorybookBehaviors({
+      adapter,
+      context: wrapperRef.current,
+    });
+  }, [adapter.attachDrupalBehaviors, html]);
+
+  return React.createElement(WrapperElement, {
+    ref: wrapperRef,
+    id: options.id,
+    className: options.className,
+    'data-emulsify-twig-story': '',
+    dangerouslySetInnerHTML: { __html: html },
+  });
+}
+
+/**
+ * React component that renders Twig HTML into a stable wrapper element.
+ *
+ * @param {object} props - Component props.
+ * @param {Function} props.template - Twig render function.
+ * @param {object} [props.args] - Storybook args.
+ * @param {object} [props.options] - Render options.
+ * @param {object} [props.storyContext] - Storybook story context.
+ * @returns {React.ReactElement} React element.
+ */
+export function TwigStory({
+  template,
+  args = {},
+  options = {},
+  storyContext = {},
+}) {
+  const [, rerender] = useReducer((version) => version + 1, 0);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return undefined;
+    }
+
+    /**
+     * Lazy `source()` calls dispatch this event after their dynamic import has
+     * populated the synchronous cache. Re-rendering here gives Twig stories the
+     * resolved source text on the next pass without blocking the first render.
+     */
+    window.addEventListener(TWIG_SOURCE_LOADED_EVENT, rerender);
+    return () => {
+      window.removeEventListener(TWIG_SOURCE_LOADED_EVENT, rerender);
+    };
+  }, []);
+
+  return React.createElement(TwigHtmlStory, {
+    html: renderTwigToHtml(template, args, options, storyContext),
+    options,
+  });
+}
+
+/**
+ * Render a raw HTML string through the same wrapper used by Twig stories.
+ *
+ * This supports legacy Storybook stories that return Twig HTML strings
+ * directly while projects migrate to `renderTwig()`.
+ *
+ * @param {string} html - Rendered HTML.
+ * @param {object} [options={}] - Render options.
+ * @returns {React.ReactElement} React element.
+ */
+export function renderTwigHtml(html, options = {}) {
+  return React.createElement(TwigHtmlStory, {
+    html: html == null ? '' : String(html),
+    options,
+  });
+}
+
+/**
+ * Convert legacy string-returning Storybook results into React elements.
+ *
+ * React stories and other non-string results pass through unchanged.
+ *
+ * @param {*} result - Story render result.
+ * @param {object} [options={}] - Render options for string results.
+ * @returns {*} React element for strings, otherwise the original result.
+ */
+export function renderHtmlStoryResult(result, options = {}) {
+  if (typeof result === 'string') {
+    return renderTwigHtml(result, options);
+  }
+
+  const legacyHtml = legacyStringFromElement(result);
+  if (typeof legacyHtml === 'string') {
+    return renderTwigHtml(legacyHtml, options);
+  }
+
+  return result;
+}
+
+/**
+ * Create a React-compatible Storybook render function for a Twig template.
+ *
+ * @param {Function} template - Imported Twig module render function.
+ * @param {object} [options={}] - Render options.
+ * @returns {Function} Storybook render function.
+ */
+export function renderTwig(template, options = {}) {
+  const EmulsifyTwigStoryRender = (args = {}, storyContext = {}) =>
+    React.createElement(TwigStory, {
+      template,
+      args,
+      options,
+      storyContext,
+    });
+
+  EmulsifyTwigStoryRender.displayName = 'EmulsifyTwigStoryRender';
+
+  return EmulsifyTwigStoryRender;
+}

package/src/storybook/twig/drupal-filters.js

@@ -0,0 +1,7 @@
+/**
+ * @file Storybook Twig.js installer for Drupal-compatible filters.
+ */
+
+import twigDrupalFilters from 'twig-drupal-filters';
+
+export default twigDrupalFilters;

package/src/storybook/twig/include-function.js

@@ -0,0 +1,109 @@
+/**
+ * @file Twig include() function factory shared by Storybook Twig renderers.
+ */
+
+const missingTemplateResolver = () => undefined;
+
+/**
+ * Normalize optional include arguments into one options object.
+ *
+ * @param {Object} variables - Explicit include variables.
+ * @param {boolean|Object} withContext - Twig with-context flag or options.
+ * @param {boolean} ignoreMissing - Twig ignore-missing flag.
+ * @returns {{variables: Object, withContext: boolean, ignoreMissing: boolean}}
+ *   Normalized include arguments.
+ */
+function normalizeIncludeOptions(
+  variables = {},
+  withContext = false,
+  ignoreMissing = false,
+) {
+  const normalizedVariables =
+    variables && typeof variables === 'object' && !Array.isArray(variables)
+      ? { ...variables }
+      : {};
+
+  if (typeof normalizedVariables.with_context !== 'undefined') {
+    withContext = normalizedVariables.with_context;
+    delete normalizedVariables.with_context;
+  }
+
+  if (typeof normalizedVariables.ignore_missing !== 'undefined') {
+    ignoreMissing = normalizedVariables.ignore_missing;
+    delete normalizedVariables.ignore_missing;
+  }
+
+  if (withContext && typeof withContext === 'object') {
+    const optionsObject = withContext;
+
+    if (typeof optionsObject.with_context !== 'undefined') {
+      withContext = optionsObject.with_context;
+    }
+    if (typeof optionsObject.ignore_missing !== 'undefined') {
+      ignoreMissing = optionsObject.ignore_missing;
+    }
+  }
+
+  return {
+    variables: normalizedVariables,
+    withContext: Boolean(withContext),
+    ignoreMissing: Boolean(ignoreMissing),
+  };
+}
+
+/**
+ * Find the first resolvable include target.
+ *
+ * @param {string|string[]} templateName - Template name or ordered candidates.
+ * @param {Function} resolver - Template resolver.
+ * @returns {Function|undefined} Resolved template render function.
+ */
+function resolveIncludeTarget(templateName, resolver) {
+  const names = Array.isArray(templateName) ? templateName : [templateName];
+
+  for (const name of names) {
+    const template = resolver(name);
+    if (template) {
+      return template;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Create a Twig.js `include()` function for Storybook rendering.
+ *
+ * @param {Function} resolver - Template resolver.
+ * @returns {Function} Twig.js function implementation.
+ */
+export function createTwigIncludeFunction(resolver = missingTemplateResolver) {
+  return function include(templateName, variables, withContext, ignoreMissing) {
+    const options = normalizeIncludeOptions(
+      variables,
+      withContext,
+      ignoreMissing,
+    );
+
+    try {
+      const templateFn = resolveIncludeTarget(templateName, resolver);
+      if (!templateFn) {
+        if (!options.ignoreMissing) {
+          console.error(`Twig include() could not resolve: ${templateName}`);
+        }
+        return '';
+      }
+
+      const finalContext = options.withContext
+        ? { ...(this?.context || {}), ...options.variables }
+        : options.variables;
+
+      return templateFn(finalContext);
+    } catch (error) {
+      if (!options.ignoreMissing) {
+        console.error(`Twig include() failed for: ${templateName}`, error);
+      }
+      return '';
+    }
+  };
+}

package/src/storybook/twig/include.js

@@ -0,0 +1,28 @@
+/**
+ * @file Twig include() runtime helper for Storybook-rendered templates.
+ */
+
+import { createTwigIncludeFunction as createIncludeFunction } from './include-function.js';
+import resolveTemplate from './resolver.js';
+
+/**
+ * Create a Twig.js `include()` function with the Storybook template resolver.
+ *
+ * @param {Function} resolver - Template resolver.
+ * @returns {Function} Twig.js function implementation.
+ */
+export function createTwigIncludeFunction(resolver = resolveTemplate) {
+  return createIncludeFunction(resolver);
+}
+
+/**
+ * Twig `include()` runtime helper.
+ *
+ * @param {Object} Twig - Twig.js module.
+ * @returns {undefined}
+ */
+function twigInclude(Twig) {
+  Twig.extendFunction('include', createIncludeFunction(resolveTemplate));
+}
+
+export default twigInclude;