@emulsify/core 4.0.4 → 4.1.1

package/config/vite/plugins/virtual-twig-asset-sources.js

@@ -16,6 +16,7 @@ export const VIRTUAL_TWIG_ASSET_SOURCES_ID =
   'virtual:emulsify-twig-asset-sources';
 const RESOLVED_VIRTUAL_TWIG_ASSET_SOURCES_ID = `\0${VIRTUAL_TWIG_ASSET_SOURCES_ID}`;
 const GENERATED_ASSET_ALIASES = new Set(['icons.svg']);
+const GENERATED_ASSET_ROOTS = ['/dist/assets'];
 const PUBLIC_ASSET_ROOTS = new Map([
   ['/assets', '/assets'],
   ['/dist/assets', '/assets'],
@@ -116,14 +117,21 @@ export function assetSourceRoots(env) {
  */
 export function generatedAssetSourceRoots(env) {
   return unique(
-    ['/dist/assets']
-      .map((root) => toAbsoluteAssetRoot(env?.projectDir, root))
+    GENERATED_ASSET_ROOTS.map((root) =>
+      toAbsoluteAssetRoot(env?.projectDir, root),
+    )
       .filter((root) => root && safeExists(root))
       .map((root) => toRootRelativePath(env?.projectDir, root))
       .filter(Boolean),
   );
 }
 
+function generatedAssetRootPrefixes() {
+  return GENERATED_ASSET_ROOTS.map((root) =>
+    `${root}/`.replace(/\/{2,}/g, '/'),
+  );
+}
+
 /**
  * Build Vite glob patterns from text asset roots.
  *
@@ -216,6 +224,20 @@ export function publicAssetSourceEntries(env) {
     }
   }
 
+  for (const root of generatedAssetRootPrefixes()) {
+    const publicBase = publicAssetBaseForRoot(root);
+    if (!publicBase) continue;
+
+    for (const alias of GENERATED_ASSET_ALIASES) {
+      const key = `${root.replace(/\/+$/, '')}/${alias}`.replace(
+        /\/{2,}/g,
+        '/',
+      );
+      const url = `${publicBase}${alias}`.replace(/\/{2,}/g, '/');
+      entries.set(key, { key, url });
+    }
+  }
+
   return Array.from(entries.values());
 }
 
@@ -232,6 +254,10 @@ export function generateVirtualTwigAssetSourcesModule(env) {
   const generatedRootPrefixes = generatedAssetSourceRoots(env).map((root) =>
     `${root === '/' ? '' : root}/`.replace(/\/{2,}/g, '/'),
   );
+  const allGeneratedRootPrefixes = unique([
+    ...generatedRootPrefixes,
+    ...generatedAssetRootPrefixes(),
+  ]);
   const patterns = assetSourceGlobPatterns(env);
   const globEntries = patterns.length
     ? patterns
@@ -255,7 +281,7 @@ export function generateVirtualTwigAssetSourcesModule(env) {
  */
 
 export const assetRootPrefixes = ${JSON.stringify(rootPrefixes)};
-export const generatedAssetRootPrefixes = ${JSON.stringify(generatedRootPrefixes)};
+export const generatedAssetRootPrefixes = ${JSON.stringify(allGeneratedRootPrefixes)};
 export const generatedAssetAliases = ${JSON.stringify(
     Array.from(GENERATED_ASSET_ALIASES),
   )};

package/config/vite/project-config.js

@@ -11,6 +11,7 @@ import { normalize, resolve, sep } from 'path';
 import { getPlatformAdapter, normalizePlatformName } from './platforms.js';
 import { resolveProjectStructure } from './project-structure.js';
 import { safeExists, safeReadJson } from './utils/fs-safe.js';
+import { unique } from './utils/unique.js';
 
 /**
  * Cache normalized project config by project root and relevant env signature.
@@ -94,6 +95,65 @@ function normalizeStructureImplementations(projectDir, implementations = []) {
     .filter(Boolean);
 }
 
+/**
+ * Read public asset root configuration from supported project config paths.
+ *
+ * `assets.roots` is the documented public path.
+ * `projectStructure.assetRoots` and `project.assetRoots` remain supported for
+ * compatibility with earlier follow-up work and local project experiments.
+ *
+ * @param {object} rawConfig - Parsed project.emulsify.json contents.
+ * @returns {Array} Raw configured asset roots.
+ */
+function rawAssetRoots(rawConfig = {}) {
+  return [
+    ...(Array.isArray(rawConfig?.assets?.roots) ? rawConfig.assets.roots : []),
+    ...(Array.isArray(rawConfig?.projectStructure?.assetRoots)
+      ? rawConfig.projectStructure.assetRoots
+      : []),
+    ...(Array.isArray(rawConfig?.project?.assetRoots)
+      ? rawConfig.project.assetRoots
+      : []),
+  ];
+}
+
+/**
+ * Normalize public asset root declarations.
+ *
+ * Paths must resolve inside the project root. Invalid entries are retained as
+ * diagnostics so the audit command can report them without making Storybook or
+ * Vite builds fail for existing projects.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {Array} roots - Raw configured asset root entries.
+ * @returns {{roots: string[], ignored: string[]}} Normalized asset root state.
+ */
+function normalizeAssetRoots(projectDir, roots = []) {
+  if (!Array.isArray(roots)) return { roots: [], ignored: [] };
+
+  const normalizedRoots = [];
+  const ignored = [];
+
+  for (const item of roots) {
+    if (typeof item !== 'string' || !item.trim()) {
+      continue;
+    }
+
+    const directory = coerceToProjectPath(projectDir, item);
+    if (!directory) {
+      ignored.push(item);
+      continue;
+    }
+
+    normalizedRoots.push(normalize(directory));
+  }
+
+  return {
+    roots: unique(normalizedRoots),
+    ignored: unique(ignored),
+  };
+}
+
 /**
  * Normalize project config for current tooling consumers.
  *
@@ -140,6 +200,7 @@ export function resolveProjectConfig(
     root,
     rawStructureImplementations,
   );
+  const assetRoots = normalizeAssetRoots(root, rawAssetRoots(rawConfig));
   const structureRoots = structureImplementations.map(
     (implementation) => implementation.directory,
   );
@@ -149,6 +210,8 @@ export function resolveProjectConfig(
     srcExists,
     SDC: singleDirectoryComponents,
     structureImplementations,
+    assetRoots: assetRoots.roots,
+    ignoredAssetRoots: assetRoots.ignored,
     platformAdapter,
   });
 
@@ -166,6 +229,8 @@ export function resolveProjectConfig(
     structureOverrides: projectStructure.structureOverrides,
     structureImplementations,
     structureRoots,
+    assetRoots: projectStructure.assetRoots,
+    ignoredAssetRoots: projectStructure.ignoredAssetRoots,
     componentRoots: projectStructure.componentRoots,
     globalRoots: projectStructure.globalRoots,
     namespaceRoots: projectStructure.namespaceRoots,

package/config/vite/project-structure.js

@@ -7,7 +7,7 @@
  * process.
  */
 
-import { basename, relative, resolve, sep } from 'path';
+import { basename, normalize, relative, resolve, sep } from 'path';
 import { safeExists } from './utils/fs-safe.js';
 import { replaceLastSlash, toPosixPath } from './utils/paths.js';
 import { unique } from './utils/unique.js';
@@ -181,6 +181,33 @@ function fallbackNamespaceRoots({
   return namespaceRoots;
 }
 
+/**
+ * Normalize project-scoped asset roots.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string[]} assetRoots - Raw asset root paths.
+ * @returns {string[]} Safe absolute asset root paths.
+ */
+function normalizeAssetRoots(projectDir, assetRoots = []) {
+  if (!Array.isArray(assetRoots)) return [];
+
+  const projectRoot = resolve(projectDir);
+
+  return unique(
+    assetRoots
+      .map((root) =>
+        typeof root === 'string' && root.trim()
+          ? normalize(resolve(projectRoot, root))
+          : '',
+      )
+      .filter(
+        (root) =>
+          root &&
+          (root === projectRoot || root.startsWith(`${projectRoot}${sep}`)),
+      ),
+  );
+}
+
 /**
  * Resolve the serializable project structure model.
  *
@@ -190,6 +217,8 @@ function fallbackNamespaceRoots({
  *   srcExists?: boolean,
  *   SDC?: boolean,
  *   structureImplementations?: {name: string, directory: string}[],
+ *   assetRoots?: string[],
+ *   ignoredAssetRoots?: string[],
  *   platformAdapter?: object
  * }} [env] - Normalized project environment.
  * @returns {object} Project structure model.
@@ -214,6 +243,8 @@ export function resolveProjectStructure(env) {
     srcDir = defaultSrcDir,
     srcExists = safeExists(defaultSrcDir),
     SDC = false,
+    assetRoots: rawAssetRoots = [],
+    ignoredAssetRoots = [],
     platformAdapter = {},
   } = resolvedEnv;
   const structureImplementations =
@@ -244,6 +275,7 @@ export function resolveProjectStructure(env) {
       });
   const componentRoots = componentRootRecords.map((root) => root.directory);
   const globalRoots = globalRootRecords.map((root) => root.directory);
+  const assetRoots = normalizeAssetRoots(projectDir, rawAssetRoots);
   const namespaceRootValues = Object.values(namespaceRoots);
   const sourceRoots = unique(
     [...componentRoots, ...globalRoots].filter(Boolean),
@@ -278,7 +310,9 @@ export function resolveProjectStructure(env) {
     globalRootRecords,
     componentRoots,
     globalRoots,
+    assetRoots,
     sourceRoots,
+    ignoredAssetRoots: unique(ignoredAssetRoots),
     sourceRootRecords,
     storyRoots,
     twigRoots,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "4.0.4",
+  "version": "4.1.1",
   "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",
@@ -38,7 +38,10 @@
     ".storybook/css-components.js",
     ".storybook/css-dist.js",
     ".storybook/emulsifyTheme.js",
+    ".storybook/main-static-assets.js",
+    ".storybook/main-vite.js",
     ".storybook/main.js",
+    ".storybook/manager-head.css",
     ".storybook/manager.js",
     ".storybook/preview.js",
     ".storybook/utils.js",
@@ -98,6 +101,7 @@
     "src/storybook/index.js",
     "src/storybook/main-config.js",
     "src/storybook/platform-behaviors.js",
+    "src/storybook/preview-decorator.js",
     "src/storybook/preview-parameters.js",
     "src/storybook/render-twig.js",
     "src/storybook/twig/include-function.js",

package/scripts/a11y.js

@@ -5,7 +5,7 @@
  * and reports issues.
  */
 
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import * as R from 'ramda';
@@ -16,15 +16,15 @@ import a11yConfig from '../config/a11y.config.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const { storybookBuildDir, pa11y: pa11yConfig } = a11yConfig;
-
 // Project-specific configuration.
-let { ignore = {}, components = [] } = a11yConfig;
+let {
+  ignore = {},
+  components = [],
+  discoverStories = true,
+  storybookBuildDir,
+  pa11y: pa11yConfig = {},
+} = a11yConfig;
 
-/** Absolute path to Storybook build directory. */
-const STORYBOOK_BUILD_DIR = path.resolve(__dirname, '../', storybookBuildDir);
-/** Absolute path to Storybook iframe file used for per-story rendering. */
-const STORYBOOK_IFRAME = path.join(STORYBOOK_BUILD_DIR, 'iframe.html');
 /** Project-specific accessibility config path used by generated themes. */
 const PROJECT_A11Y_CONFIG = path.resolve(
   __dirname,
@@ -48,12 +48,26 @@ const loadProjectA11yConfig = async () => {
 /**
  * Apply project-specific a11y config values over shared defaults.
  *
- * @param {{ignore?: object, components?: string[]}} config - Project config.
+ * @param {{ignore?: object, components?: string[], discoverStories?: boolean, storybookBuildDir?: string, pa11y?: object}} config - Project config.
  * @returns {void}
  */
 const applyProjectA11yConfig = (config = {}) => {
   ignore = config.ignore || ignore;
-  components = config.components || components;
+  components = Array.isArray(config.components)
+    ? config.components
+    : components;
+  discoverStories =
+    typeof config.discoverStories === 'boolean'
+      ? config.discoverStories
+      : discoverStories;
+  storybookBuildDir =
+    typeof config.storybookBuildDir === 'string' && config.storybookBuildDir
+      ? config.storybookBuildDir
+      : storybookBuildDir;
+  pa11yConfig =
+    config.pa11y && typeof config.pa11y === 'object'
+      ? { ...pa11yConfig, ...config.pa11y }
+      : pa11yConfig;
 };
 
 /**
@@ -67,12 +81,128 @@ const printHelp = () => {
       'Usage: node scripts/a11y.js [options]',
       '',
       'Options:',
-      '  -r           Run pa11y against configured Storybook component IDs.',
+      '  -r           Run pa11y against discovered and configured Storybook story IDs.',
       '  -h, --help   Print this help text.',
     ].join('\n'),
   );
 };
 
+/**
+ * Resolve the configured Storybook build directory.
+ *
+ * @param {string} [buildDir=storybookBuildDir] - Configured build directory.
+ * @returns {string} Absolute Storybook build directory.
+ */
+const resolveStorybookBuildDir = (buildDir = storybookBuildDir) =>
+  path.resolve(__dirname, '../', buildDir);
+
+/**
+ * Resolve Storybook's iframe file used for per-story rendering.
+ *
+ * @param {string} [buildDir=storybookBuildDir] - Configured build directory.
+ * @returns {string} Absolute iframe.html path.
+ */
+const resolveStorybookIframe = (buildDir = storybookBuildDir) =>
+  path.join(resolveStorybookBuildDir(buildDir), 'iframe.html');
+
+/**
+ * Return unique non-empty Storybook IDs in first-seen order.
+ *
+ * @param {Array} values - Candidate story IDs.
+ * @returns {string[]} Unique story IDs.
+ */
+const normalizeStoryIds = (values = []) =>
+  Array.from(
+    new Set(
+      values
+        .filter((value) => typeof value === 'string')
+        .map((value) => value.trim())
+        .filter(Boolean),
+    ),
+  );
+
+/**
+ * Extract runnable story IDs from a Storybook index object.
+ *
+ * @param {object} index - Parsed Storybook index.json or stories.json.
+ * @returns {string[]} Story IDs.
+ */
+const storyIdsFromStorybookIndex = (index = {}) => {
+  const entries =
+    index?.entries && typeof index.entries === 'object'
+      ? index.entries
+      : index?.stories && typeof index.stories === 'object'
+        ? index.stories
+        : {};
+
+  return normalizeStoryIds(
+    Object.entries(entries)
+      .filter(([, entry]) => !entry?.type || entry.type === 'story')
+      .map(([id, entry]) =>
+        typeof entry?.id === 'string' && entry.id ? entry.id : id,
+      ),
+  );
+};
+
+/**
+ * Discover runnable Storybook story IDs from built Storybook output.
+ *
+ * @param {string} [buildDir=storybookBuildDir] - Configured Storybook build directory.
+ * @param {{warn?: Function}} [options] - Reporting options.
+ * @returns {string[]} Story IDs discovered from Storybook's generated index.
+ */
+const discoverStoryIds = (
+  buildDir = storybookBuildDir,
+  { warn = console.warn } = {},
+) => {
+  const indexPath = path.join(resolveStorybookBuildDir(buildDir), 'index.json');
+
+  if (!existsSync(indexPath)) {
+    warn(
+      `Storybook index not found at ${indexPath}; falling back to configured Pa11y story IDs.`,
+    );
+    return [];
+  }
+
+  try {
+    return storyIdsFromStorybookIndex(
+      JSON.parse(readFileSync(indexPath, 'utf8')),
+    );
+  } catch (error) {
+    warn(
+      `Unable to read Storybook index at ${indexPath}: ${
+        error.message || error
+      }; falling back to configured Pa11y story IDs.`,
+    );
+    return [];
+  }
+};
+
+/**
+ * Resolve the final Pa11y story ID list.
+ *
+ * @param {object} [options={}] - Resolution options.
+ * @param {string[]} [options.manualIds=components] - Manually configured IDs.
+ * @param {boolean} [options.discover=discoverStories] - Whether discovery is enabled.
+ * @param {string} [options.buildDir=storybookBuildDir] - Storybook build directory.
+ * @param {Function} [options.warn=console.warn] - Warning sink.
+ * @returns {string[]} Story IDs to lint.
+ */
+const resolvePa11yStoryIds = ({
+  manualIds = components,
+  discover = discoverStories,
+  buildDir = storybookBuildDir,
+  warn = console.warn,
+} = {}) => {
+  const manual = normalizeStoryIds(manualIds);
+  if (discover === false) return manual;
+
+  return normalizeStoryIds([
+    ...manual,
+    ...discoverStoryIds(buildDir, { warn }),
+  ]);
+};
+
 /**
  * Map pa11y/axe severity to a label (historically a color name).
  * Retained for backward compatibility, but not used for styling anymore.
@@ -155,7 +285,7 @@ const logReport = ({ issues, pageUrl }) => {
  * @returns {Promise<{ issues: Pa11yIssue[], pageUrl: string }>} Pa11y result.
  */
 const lintComponent = async (name) =>
-  pa11y(`${STORYBOOK_IFRAME}?id=${name}`, {
+  pa11y(`${resolveStorybookIframe()}?id=${name}`, {
     includeNotices: true,
     includeWarnings: true,
     runners: ['axe'],
@@ -188,15 +318,22 @@ if (R.includes(process.argv[2], ['-h', '--help'])) {
 } else if (R.pathEq(['argv', 2], '-r')(process)) {
   loadProjectA11yConfig().then((projectConfig) => {
     applyProjectA11yConfig(projectConfig);
-    return lintReportAndExit(components);
+    return lintReportAndExit(resolvePa11yStoryIds());
   });
 }
 
 export {
   severityToColor,
+  applyProjectA11yConfig,
+  discoverStoryIds,
   issueIsValid,
   logIssue,
   logReport,
   lintComponent,
   lintReportAndExit,
+  normalizeStoryIds,
+  resolvePa11yStoryIds,
+  resolveStorybookBuildDir,
+  resolveStorybookIframe,
+  storyIdsFromStorybookIndex,
 };

package/scripts/audit.js

@@ -396,6 +396,18 @@ function auditProjectConfig(context) {
     }
   }
 
+  for (const root of env.ignoredAssetRoots || []) {
+    findings.push(
+      makeFinding({
+        id: 'invalid-asset-root',
+        severity: 'warn',
+        filePath: resolve(projectDir, 'project.emulsify.json'),
+        message: `Configured asset root "${root}" was ignored because it resolves outside the project root.`,
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md#asset-roots',
+      }),
+    );
+  }
+
   return findings;
 }
 
@@ -1046,7 +1058,7 @@ function styleRuntimeDirectories(filePath, env, projectDir) {
 function auditCssAssetReferences(context) {
   const { env, projectDir, styleFiles } = context;
   const findings = [];
-  const projectAssetsDir = resolve(projectDir, 'assets');
+  const projectAssetRoots = auditAssetRoots(env).filter(safeIsDirectory);
   const styleSourceRoots = env.projectStructure?.sourceRoots || [];
 
   for (const filePath of styleFiles) {
@@ -1092,7 +1104,7 @@ function auditCssAssetReferences(context) {
       }
 
       if (
-        isSameOrInside(resolvedAsset, projectAssetsDir) &&
+        projectAssetRoots.some((root) => isSameOrInside(resolvedAsset, root)) &&
         (!sourceAsset || runtimeAsset || assetPath.startsWith('..'))
       ) {
         findings.push(

package/src/storybook/preview-decorator.js

@@ -0,0 +1,45 @@
+/**
+ * @file Shared helpers for Storybook preview decorator wiring.
+ */
+
+import React from 'react';
+import {
+  renderHtmlStoryResult,
+  withLegacyStoryToString,
+} from './render-twig.js';
+
+/**
+ * Render a Storybook story function as a React element with full context props.
+ *
+ * @param {Function} storyFn - Storybook story function.
+ * @param {object} context - Full Storybook story context.
+ * @returns {React.ReactElement} React story element.
+ */
+export function createStoryElement(storyFn, context) {
+  return withLegacyStoryToString(React.createElement(storyFn, context), () =>
+    storyFn(context),
+  );
+}
+
+/**
+ * Apply Storybook decorators while preserving full story context.
+ *
+ * @param {Function} decorateStory - Storybook decorator applier.
+ * @param {Function} storyFn - Storybook story function.
+ * @param {Function[]} decorators - Storybook decorators.
+ * @returns {Function} Decorated story function.
+ */
+export const applyStoryDecorators = (decorateStory, storyFn, decorators) =>
+  decorateStory((context) => createStoryElement(storyFn, context), decorators);
+
+/**
+ * Render a preview Story callback through Emulsify's HTML compatibility layer.
+ *
+ * @param {Function} Story - Decorated Storybook story callback.
+ * @param {object} context - Full Storybook story context.
+ * @param {object} [options={}] - Render options.
+ * @returns {*} Rendered Storybook story result.
+ */
+export function renderPreviewStory(Story, context, options = {}) {
+  return renderHtmlStoryResult(Story(context), options);
+}