@emulsify/core 3.4.1 → 4.0.0

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

@@ -0,0 +1,239 @@
+/**
+ * @file Twig source() function factory shared by Storybook Twig renderers.
+ */
+
+import {
+  coversAssetPath,
+  getAssetText,
+  isAssetTextLoading,
+  whenAssetTextLoaded,
+} from 'virtual:emulsify-twig-asset-sources';
+import { IMAGE_ASSET_EXTS, INLINE_ASSET_EXTS } from './source-extensions.js';
+import { TWIG_SOURCE_LOADED_EVENT } from './source-events.js';
+
+const DEFAULT_ENV =
+  (typeof __EMULSIFY_ENV__ !== 'undefined' && __EMULSIFY_ENV__) || {};
+const missingTemplateSourceResolver = () => undefined;
+
+function getRuntimeEnv() {
+  return globalThis.__EMULSIFY_ENV__ || DEFAULT_ENV;
+}
+
+// GitHub Pages serves static assets from a repository-prefixed base path.
+const PUBLIC_ASSET_BASE =
+  typeof window !== 'undefined' &&
+  window.location &&
+  window.location.hostname &&
+  window.location.hostname.endsWith('github.io')
+    ? `/${getRuntimeEnv().machineName || ''}/assets/`
+    : '/assets/';
+
+const pendingSourceLoads = new Set();
+const warnedAssetSources = new Set();
+
+function allowSyncXhrSource() {
+  const adapter = getRuntimeEnv().platformAdapter || {};
+  return Boolean(
+    adapter.storybook?.allowSyncXhrSource || adapter.allowSyncXhrSource,
+  );
+}
+
+/**
+ * Normalize an `@assets` reference to a public asset path.
+ *
+ * @param {string} assetPath - Twig asset reference.
+ * @returns {string} Asset path below the public asset base.
+ */
+function normalizeAssetPath(assetPath) {
+  return assetPath.replace(/^@assets\//, '').replace(/^assets\//, '');
+}
+
+/**
+ * Read a text asset from Storybook's static server.
+ *
+ * @param {string} relPath - Public asset path below `/assets`.
+ * @returns {string|undefined} Fetched text when available.
+ */
+function fetchTextAsset(relPath) {
+  try {
+    const xhr = new XMLHttpRequest();
+    xhr.open('GET', `${PUBLIC_ASSET_BASE}${relPath}`, false);
+    xhr.send(null);
+    if (xhr.status >= 200 && xhr.status < 300) {
+      return xhr.responseText;
+    }
+
+    console.error(`source(): ${xhr.status} while fetching ${relPath}`);
+  } catch (error) {
+    console.error(`source(): failed to fetch ${relPath}`, error);
+  }
+
+  return undefined;
+}
+
+/**
+ * Warn once when a text asset cannot use the lazy virtual source map.
+ *
+ * @param {string} relPath - Public asset path below `/assets`.
+ * @param {string} reason - Short explanation of the missing source.
+ */
+function warnTextAssetSource(relPath, reason) {
+  if (warnedAssetSources.has(relPath)) {
+    return;
+  }
+
+  warnedAssetSources.add(relPath);
+  console.warn(
+    `source(): ${reason} for @assets/${relPath}. Synchronous XHR fallback is disabled by default because it blocks Storybook rendering. Move the asset under a configured asset root such as src/assets or assets, or temporarily enable platformAdapter.storybook.allowSyncXhrSource. The sync-XHR fallback is deprecated and will be removed in 4.2.`,
+  );
+}
+
+/**
+ * Notify Storybook renderers when any lazy source import is available.
+ *
+ * @param {Promise} sourceLoad - Lazy source import promise.
+ * @param {object} detail - Event detail payload.
+ */
+function scheduleSourceLoadedEvent(sourceLoad, detail) {
+  if (!sourceLoad || typeof sourceLoad.then !== 'function') {
+    return;
+  }
+  if (pendingSourceLoads.has(sourceLoad)) {
+    return;
+  }
+
+  pendingSourceLoads.add(sourceLoad);
+  sourceLoad
+    .then((sourceText) => {
+      if (
+        typeof sourceText !== 'string' ||
+        typeof window === 'undefined' ||
+        typeof window.dispatchEvent !== 'function'
+      ) {
+        return;
+      }
+
+      window.dispatchEvent(
+        new CustomEvent(TWIG_SOURCE_LOADED_EVENT, { detail }),
+      );
+    })
+    .catch(() => {})
+    .finally(() => {
+      pendingSourceLoads.delete(sourceLoad);
+    });
+}
+
+/**
+ * Resolve an `@assets` reference for Storybook.
+ *
+ * @param {string} assetPath - Twig asset reference.
+ * @param {{ ignoreMissing?: boolean }} [options={}] - Optional source() flags.
+ * @returns {string|undefined} Raw text, image markup, URL, or undefined while lazy text loads.
+ */
+export function resolveAssetSource(assetPath, { ignoreMissing = false } = {}) {
+  const relPath = normalizeAssetPath(assetPath);
+  const extension = relPath.split('.').pop().toLowerCase();
+
+  if (INLINE_ASSET_EXTS.has(extension)) {
+    const text = getAssetText(assetPath);
+    if (typeof text === 'string') {
+      return text;
+    }
+
+    if (isAssetTextLoading(assetPath)) {
+      scheduleSourceLoadedEvent(whenAssetTextLoaded(assetPath), {
+        assetPath,
+      });
+      return undefined;
+    }
+
+    if (coversAssetPath(assetPath)) {
+      if (!ignoreMissing) {
+        warnTextAssetSource(
+          relPath,
+          'no build-time text asset source was found',
+        );
+      }
+      return undefined;
+    }
+
+    if (allowSyncXhrSource()) {
+      return fetchTextAsset(relPath);
+    }
+
+    if (!ignoreMissing) {
+      warnTextAssetSource(
+        relPath,
+        'no configured build-time asset root covers',
+      );
+    }
+    return undefined;
+  }
+
+  if (IMAGE_ASSET_EXTS.has(extension)) {
+    return `<img src="${PUBLIC_ASSET_BASE}${relPath}" alt="" role="img">`;
+  }
+
+  return `${PUBLIC_ASSET_BASE}${relPath}`;
+}
+
+/**
+ * Notify Storybook renderers when a lazy Twig template source import is available.
+ *
+ * @param {Function} templateSourceResolver - Twig template source resolver.
+ * @param {string} templateName - Twig template reference.
+ */
+function scheduleTemplateSourceLoadedEvent(
+  templateSourceResolver,
+  templateName,
+) {
+  const sourceLoad =
+    typeof templateSourceResolver.whenTemplateSourceLoaded === 'function'
+      ? templateSourceResolver.whenTemplateSourceLoaded(templateName)
+      : undefined;
+
+  scheduleSourceLoadedEvent(sourceLoad, { templateName });
+}
+
+/**
+ * Create a Twig.js `source()` function for Storybook rendering.
+ *
+ * Lazy Twig source loaders return an empty string on first render while the raw
+ * source import resolves. The source text is cached by the resolver, and the
+ * Storybook Twig renderer re-renders when the load completes.
+ *
+ * @param {Function} templateSourceResolver - Twig template source resolver.
+ * @returns {Function} Twig.js function implementation.
+ */
+export function createTwigSourceFunction(
+  templateSourceResolver = missingTemplateSourceResolver,
+) {
+  return function source(templateName, ignoreMissing = false) {
+    if (typeof templateName !== 'string') return '';
+
+    const templateSource = templateSourceResolver(templateName);
+    if (typeof templateSource === 'string') {
+      return templateSource;
+    }
+    if (
+      typeof templateSourceResolver.isTemplateSourceLoading === 'function' &&
+      templateSourceResolver.isTemplateSourceLoading(templateName)
+    ) {
+      scheduleTemplateSourceLoadedEvent(templateSourceResolver, templateName);
+      return '';
+    }
+
+    if (
+      templateName.startsWith('@assets/') ||
+      templateName.startsWith('assets/')
+    ) {
+      return resolveAssetSource(templateName, { ignoreMissing }) || '';
+    }
+
+    if (!ignoreMissing) {
+      console.error(`source(): cannot resolve ${templateName}`);
+    }
+
+    return '';
+  };
+}

package/src/storybook/twig/source.js

@@ -0,0 +1,39 @@
+/**
+ * @file Twig source() runtime helper for Storybook-rendered templates.
+ */
+
+import { resolveTemplateSource } from './resolver.js';
+import {
+  createTwigSourceFunction as createSourceFunction,
+  resolveAssetSource,
+} from './source-function.js';
+
+export { resolveAssetSource };
+
+/**
+ * Create a Twig.js `source()` function for Storybook rendering.
+ *
+ * Lazy Twig source loaders return an empty string on first render while the raw
+ * source import resolves. The source text is cached by the resolver, and the
+ * Storybook Twig renderer re-renders when the load completes.
+ *
+ * @param {Function} templateSourceResolver - Twig template source resolver.
+ * @returns {Function} Twig.js function implementation.
+ */
+export function createTwigSourceFunction(
+  templateSourceResolver = resolveTemplateSource,
+) {
+  return createSourceFunction(templateSourceResolver);
+}
+
+/**
+ * Twig `source()` runtime helper.
+ *
+ * @param {Object} Twig - Twig.js module.
+ * @returns {undefined}
+ */
+function twigSource(Twig) {
+  Twig.extendFunction('source', createTwigSourceFunction());
+}
+
+export default twigSource;

package/.all-contributorsrc

@@ -1,45 +0,0 @@
-{
-  "projectName": "emulsify-core",
-  "projectOwner": "fourkitchens",
-  "repoType": "github",
-  "repoHost": "https://github.com",
-  "files": [
-    "README.md"
-  ],
-  "imageSize": 100,
-  "commit": true,
-  "commitConvention": "angular",
-  "contributors": [
-    {
-      "login": "callinmullaney",
-      "name": "Callin Mullaney",
-      "avatar_url": "https://avatars.githubusercontent.com/u/369018?v=4",
-      "profile": "https://github.com/callinmullaney",
-      "contributions": ["code", "doc"]
-    },
-    {
-      "login": "amazingrando",
-      "name": "Randy Oest",
-      "avatar_url": "https://avatars.githubusercontent.com/u/409903?v=4",
-      "profile": "https://github.com/amazingrando",
-      "contributions": ["code", "doc"]
-    },
-    {
-      "login": "robherba",
-      "name": "Roberto Hernandez",
-      "avatar_url": "https://avatars.githubusercontent.com/u/9342274?v=4",
-      "profile": "https://github.com/robherba",
-      "contributions": ["code"]
-    },
-    {
-      "login": "dependabot",
-      "name": "Dependabot",
-      "avatar_url": "https://avatars.githubusercontent.com/u/49699333?v=4",
-      "profile": "https://github.com/dependabot",
-      "contributions": ["maintenance"]
-    }
-  ],
-  
-  "contributorsPerLine": 6,
-  "skipCi": true
-} 

package/.editorconfig

@@ -1,5 +0,0 @@
-# Unix-style newlines with a newline ending every file
-[*]
-indent_style = space
-indent_size = 2
-insert_final_newline = true

package/.github/ISSUE_TEMPLATE/BUG_REPORT_TEMPLATE.md

@@ -1,18 +0,0 @@
-### Describe the bug
-_A clear and concise description of what the bug is._
-
-### Steps to reproduce the bug
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-### Expected behavior
-A clear and concise description of what you expected to happen.
-
-### Suggested solution or approach:
-_(optional) Describe a solution or approach to your request that may help with implementation._
-
-### Additional context
-_(optional) Add any other context or screenshots about the feature request here._

package/.github/ISSUE_TEMPLATE/FEATURE_REQUEST_TEMPLATE.md

@@ -1,11 +0,0 @@
-### Emulsify Core Version:
-- [1.0.0](https://github.com/emulsify-ds/emulsify-core/releases)):
-
-### Description of the feature request:
-_Please give as much information as possible_ 
-
-### Suggested solution or approach:
-_(optional) Describe a solution or approach to your request that may help with implementation._
-
-### Additional context:
-_(optional) Add any other context or screenshots about the feature request here._

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,19 +0,0 @@
-**This PR does the following:**
-- Adds functionality bullet item
-- Fixes this or that bullet item
-  
-### Related Issue(s)
-- [Title of the issue](https://github.com/emulsify-ds/emulsify-core/issues/1)
-
-### Notes:
-- (optional) Document any intentionally unfinished parts or known issues within this PR
-
-### Functional Testing:
-- [ ] Document steps that allow someone to fully test your code changes. Include screenshot and links when appropriate.
-
-### Security
-_Security checks that should be reviewed_
-
-### Accessibility
-_Should this be checked for this feature?_
-

package/.github/dependabot.yml

@@ -1,6 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: npm
-    directory: "/"
-    schedule:
-      interval: weekly

package/.github/workflows/addtoprojects.yml

@@ -1,21 +0,0 @@
-name: Add to projects
-
-on:
-  issues:
-    types:
-      - opened
-  pull_request:
-    types:
-      - opened
-
-jobs:
-  add-to-project:
-    name: Add issue to project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.3.0
-        with:
-          # You can target a repository in a different organization
-          # to the issue
-          project-url: https://github.com/emulsify-ds/emulsify-core
-          github-token: ${{ secrets.GH_TOKEN }}

package/.github/workflows/contributors.yml

@@ -1,37 +0,0 @@
-name: Add contributors
-on:
-  push:
-    branches:
-      - main
-      - develop
-  workflow_dispatch:
-
-jobs:
-  add-contributors:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.CONTRIBUTORS_TOKEN }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "24"
-
-      - name: Install all-contributors-cli
-        run: npm install -g all-contributors-cli
-
-      - name: Generate contributors
-        run: |
-          all-contributors generate
-          git config --global user.name 'GitHub Actions'
-          git config --global user.email 'github-actions@github.com'
-          git add README.md
-          git commit -m "docs: update contributors" || exit 0
-          git push
-        env:
-          GITHUB_TOKEN: ${{ secrets.CONTRIBUTORS_TOKEN }}

package/.github/workflows/lint.yml

@@ -1,22 +0,0 @@
-name: Lint
-on:
-  push:
-    branches: [develop, main]
-  pull_request:
-    branches: [develop, main]
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Install Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "24"
-      - name: Install
-        run: npm install
-      - name: Lint
-        run: npm run lint

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

@@ -1,24 +0,0 @@
-name: Semantic Release on Merge
-on:
-  push:
-    branches: [main]
-jobs:
-  release:
-    name: Attempt Semantic Release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Install Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "24.x"
-      - name: Install
-        run: npm install
-      - name: Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm run semantic-release

package/.husky/commit-msg

@@ -1,2 +0,0 @@
-#!/bin/sh
-npm run husky:commit-msg

package/.husky/pre-commit

@@ -1,2 +0,0 @@
-#!/bin/sh
-npm run husky:pre-commit

package/.nvmrc

@@ -1 +0,0 @@
-24

package/.prettierignore

@@ -1,4 +0,0 @@
-dist
-.out
-.coverage
-*.min.js

package/.storybook/polyfills/twig-include.js

@@ -1,36 +0,0 @@
-
-import resolveTemplate from './twig-resolver.js';
-
-/**
- * Twig `include()` polyfill.
- * Mirrors Drupal behaviour inside Storybook.
- * @param {string} templateName
- * @param {Object} [variables]
- * @param {boolean} [withContext=false]
- * @return {string}
- */
-function twigInclude(Twig) {
-  Twig.extendFunction('include', (...args) => {
-    let [templateName, variables = {}, withContext = false] = args;
-    if (typeof withContext !== 'boolean' && variables && typeof variables.with_context !== 'undefined') {
-      withContext = variables.with_context;
-      delete variables.with_context;
-    }
-
-    try {
-      const templateFn = resolveTemplate(templateName);
-      if (!templateFn) return '';
-
-      const finalContext = withContext && typeof this === 'object'
-        ? { ...(this.context || {}), ...variables }
-        : variables;
-
-      return templateFn(finalContext);
-    } catch (err) {
-      console.error(`Twig include() failed for: ${templateName}`, err);
-      return '';
-    }
-  });
-};
-
-export default twigInclude;

package/.storybook/polyfills/twig-resolver.js

@@ -1,68 +0,0 @@
-import { getProjectMachineName } from '../utils';
-
-const namespace = getProjectMachineName();
-
-const twigComponents = require.context(
-  '../../../../../src/components/',
-  true,
-  /\.twig$/
-);
-
-/**
- * Resolve template identifier to compiled Twig function.
- * Supports: @component.twig, namespace:component, @namespace/component, namespace/component
- * @param {string} name Template identifier
- * @returns {Function|undefined} Compiled function or noop
- */
-function resolveTemplate(name) {
-  // namespace:icon, @namespace/icon.twig
-  if (name.startsWith(`${namespace}:`) || name.startsWith(`@${namespace}/`)) {
-    const part = name.startsWith(`${namespace}:`) ? name.split(':')[1] : name.replace(`${namespace}/`, '').replace('.twig', '');
-    const path = `./${part}/${part}.twig`;
-    try {
-      {
-        const mod = twigComponents(path);
-        return mod && mod.default ? mod.default : mod;
-      }
-    } catch (e) {
-      // eslint-disable-next-line no-console
-      console.error(`Cannot resolve Twig component for '${name}' at '${path}'`);
-    }
-  }
-
-  // @icon.twig → icon/icon.twig
-  if (name.startsWith('@') && name.endsWith('.twig')) {
-    const part = name.slice(1, -5); // remove leading @ and trailing .twig
-    const path = `./${part}/${part}.twig`;
-    try {
-      return twigComponents(path).default || twigComponents(path);
-    } catch (e) {
-      console.error(`Cannot resolve Twig shorthand template '${name}' at '${path}'`);
-    }
-  }
-
-  // namespace/icon.twig via webpack alias
-  if (name.startsWith(`${namespace}/`)) {
-    const part = name.replace(new RegExp(`^${namespace}/`), '').replace('.twig', '');
-    const path = `./${part}/${part}.twig`;
-    try {
-      return twigComponents(path).default || twigComponents(path);
-    } catch (e) {
-      console.error(`Cannot resolve Twig alias template '${name}' at '${path}'`);
-    }
-  }
-
-  try {
-    {
-      // eslint-disable-next-line import/no-dynamic-require, global-require
-      const mod = require(name);
-      return mod && mod.default ? mod.default : mod;
-    }
-  } catch (e) {
-    // eslint-disable-next-line no-console
-    console.error(`Cannot resolve Twig template '${name}'`, e);
-    return () => '';
-  }
-};
-
-export default resolveTemplate;

package/.storybook/polyfills/twig-source.js

@@ -1,54 +0,0 @@
-import { getProjectMachineName } from '../utils';
-
-const namespace = getProjectMachineName();
-
-// Constants used by the `source()` polyfill.
-const PUBLIC_ASSET_BASE = (typeof window !== 'undefined' && window.location && window.location.hostname && window.location.hostname.endsWith('github.io'))
-  ? `/${namespace}/assets/`
-  : '/assets/';
-
-const INLINE_ASSET_EXTS = new Set(['svg', 'html', 'twig', 'css', 'js', 'json', 'txt', 'md']);
-const IMAGE_ASSET_EXTS  = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']);
-
-/**
- * Twig `source()` polyfill.
- * Returns an <img> tag or URL for @assets paths.
- * @param {string} assetPath
- * @return {string}
- */
-function twigSource(Twig) {
-  Twig.extendFunction('source', (assetPath) => {
-    if (typeof assetPath !== 'string') return '';
-
-    // Strip Drupal-style alias and extract file extension.
-    const relPath = assetPath.replace(/^@assets\//, '');
-    const extension = relPath.split('.').pop().toLowerCase();
-
-    // Inline raw content for textual assets.
-    if (INLINE_ASSET_EXTS.has(extension)) {
-      try {
-        const xhr = new XMLHttpRequest();
-        xhr.open('GET', `${PUBLIC_ASSET_BASE}${relPath}`, false); // synchronous
-        xhr.send(null);
-        if (xhr.status >= 200 && xhr.status < 300) {
-          return xhr.responseText;
-        }
-        // eslint-disable-next-line no-console
-        console.error(`source(): ${xhr.status} while fetching ${relPath}`);
-      } catch (err) {
-        // eslint-disable-next-line no-console
-        console.error(`source(): failed to fetch ${relPath}`, err);
-      }
-    }
-
-    // Auto-render raster images.
-    if (IMAGE_ASSET_EXTS.has(extension)) {
-      return `<img src="${PUBLIC_ASSET_BASE}${relPath}" alt="" role="img">`;
-    }
-
-    // Fallback: return public URL.
-    return `${PUBLIC_ASSET_BASE}${relPath}`;
-  });
-};
-
-export default twigSource;