@emulsify/core 2.7.1 → 3.0.1

package/.github/workflows/semantic-release.yml

@@ -8,13 +8,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Install Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: "24.x"
       - name: Install
         run: npm install
       - name: Release

package/.nvmrc

@@ -1 +1 @@
-20
+24

package/.storybook/_drupal.js

@@ -1,19 +1,41 @@
 // Simple Drupal.behaviors usage for Storybook
 
+/**
+ * Global Drupal namespace stub for Storybook environment.
+ * @namespace Drupal
+ */
 window.Drupal = { behaviors: {} };
 
+/**
+ * Immediately-Invoked Function Expression to scope Drupal behavior attachment logic.
+ * @param {Object} Drupal - The Drupal global namespace object.
+ * @param {Object} drupalSettings - Global Drupal settings object stub.
+ */
 (function (Drupal, drupalSettings) {
+  /**
+   * Throws an error asynchronously to avoid interrupting execution flow.
+   * @param {Error} error - The error object to throw.
+   * @returns {void}
+   */
   Drupal.throwError = function (error) {
     setTimeout(function () {
       throw error;
     }, 0);
   };
 
+  /**
+   * Attaches all registered Drupal behaviors.
+   * @param {HTMLElement|Document} [context=document] - DOM context to attach behaviors to.
+   * @param {Object} [settings=drupalSettings] - Drupal settings to pass to behaviors.
+   * @returns {void}
+   */
   Drupal.attachBehaviors = function (context, settings) {
     context = context || document;
     settings = settings || drupalSettings;
+    /** @type {Object.<string, {attach: Function}>} */
     const behaviors = Drupal.behaviors;
 
+    // Iterate through each behavior and invoke its attach method if defined.
     Object.keys(behaviors).forEach(function (i) {
       if (typeof behaviors[i].attach === 'function') {
         try {

package/.storybook/emulsifyTheme.js

@@ -1,5 +1,4 @@
 // Documentation on theming Storybook: https://storybook.js.org/docs/configurations/theming/
-
 import { create } from '@storybook/theming';
 
 export default create({
@@ -34,5 +33,5 @@ export default create({
   brandTitle: 'Emulsify',
   brandUrl: 'https://emulsify.info',
   brandImage:
-    'https://raw.githubusercontent.com/fourkitchens/emulsify-core/main/assets/images/emulsify-logo-sb.svg?token=GHSAT0AAAAAACIEXLVC5R3KBCX6HGKGTBBSZNYFWMA',
+    'https://raw.githubusercontent.com/fourkitchens/emulsify-core/main/assets/images/emulsify-logo-sb.svg',
 });

package/.storybook/main.js

@@ -1,36 +1,107 @@
-const { configOverrides } = require('../../../../config/emulsify-core/storybook/main');
-
+// .storybook/main.js
+
+/**
+ * Storybook main configuration file.
+ * This configures stories, static directories, addons, core builder,
+ * framework, documentation settings, manager head styles, and overrides.
+ * @module .storybook/main
+ */
+
+import { resolve } from 'path';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import configOverrides from '../../../../config/emulsify-core/storybook/main.js';
+
+/**
+ * The full path to the current file (ESM compatible).
+ * @type {string}
+ */
+const __filename = fileURLToPath(import.meta.url);
+
+/**
+ * The directory name of the current module file.
+ * @type {string}
+ */
+const __dirname  = path.dirname(__filename);
+
+/**
+ * Safely apply any user-provided overrides or fall back to an empty object.
+ * @type {object}
+ */
 const safeConfigOverrides = configOverrides || {};
 
+/**
+ * Primary Storybook configuration object.
+ * @type {import('@storybook/core-common').StorybookConfig}
+ */
 const config = {
+  /**
+   * Patterns for locating story files under src or components directories.
+   * @type {string[]}
+   */
   stories: [
     '../../../../(src|components)/**/*.stories.@(js|jsx|ts|tsx)',
   ],
+
+  /**
+   * Directories to serve as static assets in the Storybook build.
+   * @type {string[]}
+   */
   staticDirs: [
     '../../../../assets/images',
     '../../../../assets/icons',
     '../../../../dist',
   ],
+
+  /**
+   * List of Storybook addons to enable various features.
+   * @type {string[]}
+   */
   addons: [
     '../../../@storybook/addon-a11y',
     '../../../@storybook/addon-links',
     '../../../@storybook/addon-essentials',
     '../../../@storybook/addon-themes',
-    '../../../@storybook/addon-styling-webpack'
+    '../../../@storybook/addon-styling-webpack',
   ],
+
+  /**
+   * Core builder configuration for Storybook.
+   * @type {{builder: string, disableTelemetry: boolean}}
+   */
   core: {
     builder: 'webpack5',
+    disableTelemetry: true,
   },
+
+  /**
+   * Framework specification for Storybook (HTML + Webpack5).
+   * @type {{name: string, options: object}}
+   */
   framework: {
     name: '@storybook/html-webpack5',
     options: {},
   },
+
+  /**
+   * Documentation settings for Storybook autodocs.
+   * @type {{autodocs: boolean}}
+   */
   docs: {
     autodocs: false,
   },
-  managerHead: (head) => `
-    ${head}
-    <style>
+
+  /**
+   * Custom styles injected into the Storybook manager (sidebar) head,
+   * plus any external manager-head.html snippet.
+   * @param {string} head - Existing head HTML.
+   * @returns {string} Modified head HTML.
+   */
+  managerHead: (head) => {
+    // inline theme styles
+    const inlineStyles = `
+      <style>
       :root {
         --colors-emulsify-blue-100: #e6f5fc;
         --colors-emulsify-blue-200: #CCECFA;
@@ -44,41 +115,33 @@ const config = {
         --colors-emulsify-blue-1000: #00202e;
         --colors-purple: #8B1E7E;
       }
-
       .sidebar-container {
         background: url('https://raw.githubusercontent.com/fourkitchens/emulsify-core/main/assets/images/corner-bkg.png?token=GHSAT0AAAAAACIEXLVDMX56QK3ZIZWHWHTEZNYFYIA') no-repeat top left;
       }
-
       .sidebar-container .sidebar-subheading {
         color: var(--colors-emulsify-blue-200);
         font-size: 13px;
         letter-spacing: 0.15em;
       }
-
       .sidebar-container .sidebar-subheading button:focus {
         color: var(--colors-emulsify-blue-300);
       }
-
       /** Triangle icon **/
       .sidebar-container .sidebar-subheading button span {
         color: var(--colors-emulsify-blue-300);
       }
-
       .sidebar-container .search-field input {
         border-color: var(--colors-emulsify-blue-700);
       }
-
       .sidebar-container .search-field input:active {
         border-color: var(--colors-emulsify-blue-700);
       }
-
       .sidebar-container .search-result-recentlyOpened,
       .sidebar-container .search-result-back,
       .sidebar-container .search-result-clearHistory {
         color: var(--colors-emulsify-blue-300) !important;
         letter-spacing: 0.15em;
       }
-
       .sidebar-container .search-result-back span,
       .sidebar-container .search-result-back svg,
       .sidebar-container .search-result-clearHistory span,
@@ -86,74 +149,96 @@ const config = {
         letter-spacing: normal;
         color: white;
       }
-
       .sidebar-container .sidebar-item svg {
         margin-top: 1px;
       }
-
       .sidebar-container .sidebar-item span {
         margin-top: 4px;
       }
-
       .sidebar-container .sidebar-subheading-action svg {
         color: var(--colors-emulsify-blue-400);
       }
-
       .sidebar-container .sidebar-subheading-action:hover svg {
         color: var(--colors-emulsify-blue-300);
       }
-
       .sidebar-header button[title="Shortcuts"] {
         box-shadow: none;
         border: 1px solid var(--colors-emulsify-blue-700);
       }
-
       .sidebar-header button[title="Shortcuts"]:active {
         border: 1px solid var(--colors-emulsify-blue-500);
       }
-
       .sidebar-header button[title="Shortcuts"]:focus {
         background: transparent;
       }
-
       #shortcuts {
         border-bottom-color: var(--colors-emulsify-blue-900) !important;
       }
-
       [role="main"]:not(:nth-child(3)) {
         top: 1rem !important;
         height: calc(100vh - 2rem) !important;
       }
-
       [role="main"] .os-host .os-content button:hover {
         background: var(--colors-emulsify-blue-100);
       }
-
       [role="main"] .os-host .os-content button:hover svg {
         color: var(--colors-emulsify-blue-900);
       }
-
       #panel-tab-content,
       #panel-tab-content>* {
         color: var(--colors-emulsify-blue-100) !important;
       }
-
       #panel-tab-content a,
       #panel-tab-content a span,
       #panel-tab-content a span svg {
         color: var(--colors-emulsify-blue-800);
       }
-
       #panel-tab-content>div>div>div>div>div>div {
         background: transparent;
       }
-
       #panel-tab-content>div>div>div>div>div>div>div {
         color: var(--colors-emulsify-blue-1000) !important;
       }
     </style>
-  `,
+    `;
+
+    // load external manager-head.html if present
+    const externalManagerHeadPath = resolve(
+      __dirname,
+      '../../../../config/emulsify-core/storybook/manager-head.html'
+    );
+    let externalManagerHtml = '';
+    if (fs.existsSync(externalManagerHeadPath)) {
+      externalManagerHtml = fs.readFileSync(externalManagerHeadPath, 'utf8');
+    }
+
+    return `${head}
+${inlineStyles}
+${externalManagerHtml}`;
+  },
+
+  /**
+   * Function to load and append an external preview-head.html into the preview iframe.
+   * @param {string} head - Existing preview head HTML.
+   * @returns {string} Combined head HTML including external snippet if present.
+   */
+  previewHead: (head) => {
+    const externalHeadPath = resolve(
+      __dirname,
+      '../../../../config/emulsify-core/storybook/preview-head.html'
+    );
+
+    let externalHtml = '';
+    if (fs.existsSync(externalHeadPath)) {
+      externalHtml = fs.readFileSync(externalHeadPath, 'utf8');
+    }
+
+    return `${head}
+${externalHtml}`;
+  },
+
+  // Merge in user overrides without modifying original logic
   ...safeConfigOverrides,
 };
 
-module.exports = config;
+export default config;

package/.storybook/manager.js

@@ -1,14 +1,45 @@
+// .storybook/manager.js
+
 import { addons } from '@storybook/manager-api';
 import emulsifyTheme from './emulsifyTheme';
 
+/**
+ * Dynamically import the user-provided Storybook theme override.
+ * Falls back to the default Emulsify theme if the import fails or is empty.
+ */
 import('../../../../config/emulsify-core/storybook/theme')
-.then((customTheme) => {
-  addons.setConfig({
-    theme: customTheme.default,
-  });
-})
-.catch(() => {
-  addons.setConfig({
-    theme: emulsifyTheme,
+  /**
+   * Handle successful dynamic import of the theme module.
+   * @param {{ default: object }} module - The imported theme module.
+   */
+  .then(({ default: customTheme }) => {
+    /**
+     * Determine if the imported theme object is empty or not.
+     * @type {boolean}
+     */
+    const isEmptyObject =
+      !customTheme ||
+      (typeof customTheme === 'object' && Object.keys(customTheme).length === 0);
+
+    /**
+     * Apply the chosen theme to Storybook’s manager UI configuration.
+     * @type {{ theme: object }}
+     */
+    addons.setConfig({
+      theme: isEmptyObject ? emulsifyTheme : customTheme,
+    });
+  })
+  /**
+   * Handle failure of the dynamic import (e.g., file not found).
+   * @returns {void}
+   */
+  .catch(() => {
+    addons.setConfig({
+      /**
+       * Fallback to the default Emulsify theme on import error.
+       * @type {{ theme: object }}
+       */
+      theme: emulsifyTheme,
+    });
   });
-});
+  

package/.storybook/preview.js

@@ -1,32 +1,75 @@
+// .storybook/preview.js
 import { useEffect } from '@storybook/preview-api';
 import Twig from 'twig';
 import { setupTwig, fetchCSSFiles } from './utils.js';
-import { getRules } from "axe-core";
+import { getRules } from 'axe-core';
 
-// If in a Drupal project, it's recommended to import a symlinked version of drupal.js.
+/**
+ * External override parameters loaded from project config file, if present.
+ * @type {object}
+ */
+let externalOverrides = {};
+
+// Load the preview.js from the project config overrides.
+try {
+  /**
+   * Dynamically require external preview overrides.
+   * @module '../../../../config/emulsify-core/storybook/preview.js'
+   */
+  externalOverrides = require(
+    '../../../../config/emulsify-core/storybook/preview.js'
+  ).default;
+} catch (err) {
+  // no override file? swallow the error and use {}
+  externalOverrides = {};
+}
+
+// Import Drupal behaviors for rich JavaScript integration.
 import './_drupal.js';
 
+/**
+ * Filters accessibility rules by matching tags.
+ * @param {string[]} [tags=[]] List of WCAG rule tags to enable.
+ * @returns {{id: string, enabled: boolean}[]} Array of rule configurations.
+ */
 function enableRulesByTag(tags = []) {
   const allRules = getRules();
   return allRules.map(rule =>
-    tags.some(t => rule.tags.includes(t)) ? { id: rule.ruleId, enabled: true } : { id: rule.ruleId, enabled: false }
+    tags.some(t => rule.tags.includes(t))
+      ? { id: rule.ruleId, enabled: true }
+      : { id: rule.ruleId, enabled: false }
   );
 }
 
+/**
+ * Precomputed Axe accessibility rules enabled by default.
+ * @type {{id: string, enabled: boolean}[]}
+ */
 const AxeRules = enableRulesByTag([
-  "wcag2a",
-  "wcag2aa",
-  "wcag21a",
-  "wcag21aa",
-  "wcag22aa",
-  "best-practice",
+  'wcag2a',
+  'wcag2aa',
+  'wcag21a',
+  'wcag21aa',
+  'wcag22aa',
+  'best-practice',
 ]);
 
+// Initialize Twig and load any CSS that your stories need.
+setupTwig(Twig);
+fetchCSSFiles();
+
+/**
+ * Storybook decorators to apply Drupal behaviors before rendering each story.
+ * @type {Array<import('@storybook/react').Decorator>}
+ */
 export const decorators = [
+  /**
+   * Decorator that attaches Drupal behaviors on story mount.
+   * @param {Function} Story The story component to render.
+   * @param {object} context Story context including args.
+   * @returns {Function} Rendered story.
+   */
   (Story, { args }) => {
-    const { renderAs } = args || {};
-
-    // Usual emulsify hack to add Drupal behaviors.
     useEffect(() => {
       Drupal.attachBehaviors();
     }, [args]);
@@ -34,18 +77,27 @@ export const decorators = [
   },
 ];
 
-setupTwig(Twig);
-fetchCSSFiles();
-
-export const parameters = {
+/**
+ * Default Storybook parameters before applying overrides.
+ * @type {object}
+ */
+const defaultParams = {
   actions: { argTypesRegex: '^on[A-Z].*' },
   a11y: {
     config: {
       detailedReport: true,
-      detailedReportOptions: {
-        html: true,
-      },
+      detailedReportOptions: { html: true },
       rules: AxeRules,
     },
   },
+  layout: 'fullscreen',
+};
+
+/**
+ * Merged Storybook parameters including external overrides.
+ * @type {object}
+ */
+export const parameters = {
+  ...defaultParams,
+  ...externalOverrides,
 };

package/.storybook/utils.js

@@ -1,17 +1,28 @@
-const { resolve } = require('path');
-const twigDrupal = require('twig-drupal-filters');
-const twigBEM = require('bem-twig-extension');
-const twigAddAttributes = require('add-attributes-twig-extension');
+import { resolve, dirname } from 'path';
+import twigDrupal from 'twig-drupal-filters';
+import twigBEM from 'bem-twig-extension';
+import twigAddAttributes from 'add-attributes-twig-extension';
+import emulsifyConfig from '../../../../project.emulsify.json' with { type: 'json' };
+
+// Create __filename from import.meta.url without fileURLToPath
+let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
+
+// On Windows, remove the leading slash (e.g. "/C:/path" -> "C:/path")
+if (process.platform === 'win32' && _filename.startsWith('/')) {
+  _filename = _filename.slice(1);
+}
+
+const _dirname = dirname(_filename);
 
 /**
  * Fetches project-based variant configuration. If no such configuration
  * exists, returns default values as a flat component structure.
  *
- * @returns project-based variant configuration, or default config.
+ * @returns {Array} project-based variant configuration, or default config.
  */
 const fetchVariantConfig = () => {
   try {
-    return require('../../../../project.emulsify.json').variant.structureImplementations;
+    return emulsifyConfig.variant.structureImplementations;
   } catch (e) {
     return [
       {
@@ -32,38 +43,37 @@ const fetchCSSFiles = () => {
   try {
     // Load all CSS files from 'dist'.
     const cssFiles = require.context('../../../../dist', true, /\.css$/);
-    cssFiles.keys().forEach(file => cssFiles(file));
+    cssFiles.keys().forEach((file) => cssFiles(file));
 
     // Load all CSS files from 'components' for 'drupal' platform.
-    const emulsifyConfig = require('../../../../project.emulsify.json');
     if (emulsifyConfig.project.platform === 'drupal') {
       const drupalCSSFiles = require.context('../../../../components', true, /\.css$/);
-      drupalCSSFiles.keys().forEach(file => drupalCSSFiles(file));
+      drupalCSSFiles.keys().forEach((file) => drupalCSSFiles(file));
     }
   } catch (e) {
     return undefined;
   }
 };
 
-module.exports.namespaces = {};
+// Build namespaces mapping.
+export const namespaces = {};
 for (const { name, directory } of fetchVariantConfig()) {
-  module.exports.namespaces[name] = resolve(__dirname, '../../../../', directory);
+  namespaces[name] = resolve(_dirname, '../../../../', directory);
 }
 
 /**
- * Configures and extends a standard twig object.
+ * Configures and extends a standard Twig object.
  *
- * @param {Twig} twig - twig object that should be configured and extended.
- *
- * @returns {Twig} configured twig object.
+ * @param {Object} twig - Twig object that should be configured and extended.
+ * @returns {Object} Configured Twig object.
  */
-module.exports.setupTwig = function setupTwig(twig) {
+export function setupTwig(twig) {
   twig.cache();
   twigDrupal(twig);
   twigBEM(twig);
   twigAddAttributes(twig);
   return twig;
-};
+}
 
-// Export the fetchCSSFiles function
-module.exports.fetchCSSFiles = fetchCSSFiles;
+// Export the fetchCSSFiles function.
+export { fetchCSSFiles };