@storybook-astro/framework 0.1.0-beta.8 → 1.0.0

package/src/middleware.ts

@@ -1,149 +1,257 @@
+import { pathToFileURL } from 'node:url';
 import { experimental_AstroContainer as AstroContainer } from 'astro/container';
 import type { Integration } from './integrations/index.ts';
-import { addRenderers } from 'virtual:astro-container-renderers';
+import type { SanitizationOptions } from './lib/sanitization.ts';
+import { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';
+import { resolveStoryModuleMock, withStoryModuleMocks } from './module-mocks.ts';
+import { applyMswHandlers } from './msw.ts';
+import { selectStoryRules } from './rules.ts';
+import type { RenderStoryInput } from './types.ts';
+import { addRenderers, resolveClientModules } from 'virtual:astro-container-renderers';
+
+type ResolveRulesConfigModule = () => unknown | Promise<unknown>;
+
+type AstroCreateResult = {
+  createAstro?: (...args: unknown[]) => unknown;
+};
+
+type AstroComponentFactory = ((
+  result: AstroCreateResult,
+  props: unknown,
+  slots: unknown
+) => unknown) & {
+  isAstroComponentFactory?: boolean;
+  moduleId?: string;
+  propagation?: unknown;
+};
 
 export type HandlerProps = {
   component: string;
   args?: Record<string, unknown>;
   slots?: Record<string, unknown>;
+  story?: RenderStoryInput;
+};
+
+type HandlerFactoryOptions = {
+  mode?: 'development' | 'production';
+  sanitization?: SanitizationOptions;
+  rulesConfigFilePath?: string;
+  resolveRulesConfigModule?: ResolveRulesConfigModule;
+  loadModule?: (id: string) => Promise<{ default: unknown }>;
 };
 
-export async function handlerFactory(integrations: Integration[]) {
-  const safeIntegrations = integrations ?? [];
+export async function handlerFactory(_integrations: Integration[], options?: HandlerFactoryOptions) {
+  const mode = options?.mode ?? 'development';
   const container = await AstroContainer.create({
     // Somewhat hacky way to force client-side Storybook's Vite to resolve modules properly
-    resolve: async (s) => {
-      if (s.startsWith('astro:scripts')) {
-        return `/@id/${s}`;
+    resolve: async (specifier) => {
+      const mockedModule = resolveStoryModuleMock(specifier);
+
+      if (mockedModule) {
+        return mockedModule;
+      }
+
+      if (specifier.startsWith('astro:scripts')) {
+        return `/@id/${specifier}`;
       }
 
-      for (const integration of safeIntegrations) {
-        const resolution = integration.resolveClient(s);
+      const resolution = resolveClientModules(specifier);
 
-        if (resolution) {
-          return resolution;
-        }
+      if (resolution) {
+        return resolution;
       }
 
-      return s;
+      return specifier;
     }
   });
 
   addRenderers(container);
+  const sanitizationOptions = resolveSanitizationOptions(options?.sanitization);
+  const loadModule =
+    options?.loadModule ??
+    ((id: string) => {
+      const normalizedId = /^[a-zA-Z]:[/\\]/.test(id) ? pathToFileURL(id).href : id;
 
-  return async function handler(data: HandlerProps) {
-    const { default: Component } = await import(/* @vite-ignore */ data.component);
-
-    // Process args to convert ImageMetadata objects to usable URLs
-    const processedArgs = await processImageMetadata(data.args || {});
-
-    // Wrap the component factory to fix the createAstro calling convention mismatch.
-    // Astro compiler v2 produces: result.createAstro($$Astro, $$props, $$slots) [3 args]
-    // Astro 6 runtime expects: result.createAstro($$props, $$slots) [2 args]
-    // When v2-compiled components run against the v6 runtime, $$Astro gets captured as
-    // "props" and actual props end up as "slots". This wrapper detects the 3-arg call
-    // and strips the leading $$Astro argument.
-    const patchedComponent = patchCreateAstroCompat(Component);
-
-    const result = await container.renderToString(patchedComponent, {
-      props: processedArgs,
-      slots: data.slots ?? {}
+      return import(/* @vite-ignore */ normalizedId);
     });
+  const componentCache = new Map<string, Promise<AstroComponentFactory>>();
+  let renderQueue = Promise.resolve<void>(undefined);
+
+  async function loadPatchedComponent(componentId: string, useCache = true) {
+    if (!useCache) {
+      const { default: component } = await loadModule(componentId);
+
+      return patchCreateAstroCompat(component);
+    }
+
+    if (!componentCache.has(componentId)) {
+      componentCache.set(componentId, (async () => {
+        const { default: component } = await loadModule(componentId);
+
+        return patchCreateAstroCompat(component);
+      })());
+    }
+
+    const cachedComponent = componentCache.get(componentId);
+
+    if (!cachedComponent) {
+      throw new Error(`Failed to load Astro component: ${componentId}`);
+    }
+
+    try {
+      return await cachedComponent;
+    } catch (error) {
+      // Drop failed entries so transient/module errors can recover on the next request.
+      componentCache.delete(componentId);
+      throw error;
+    }
+  }
+
+  return async function handler(data: HandlerProps) {
+    const executeRender = async () => {
+      const rulesConfigModule = options?.resolveRulesConfigModule
+        ? await options.resolveRulesConfigModule()
+        : undefined;
+
+      const selectedRules = await selectStoryRules({
+        configModule: rulesConfigModule,
+        configFilePath: options?.rulesConfigFilePath,
+        mode,
+        story: data.story
+      });
+
+      await applyMswHandlers(selectedRules.mswHandlers);
 
-    return result;
+      return withStoryModuleMocks(selectedRules.moduleMocks, async () => {
+        const patchedComponent = await loadPatchedComponent(
+          data.component,
+          selectedRules.moduleMocks.size === 0
+        );
+        const processedArgs = await processImageMetadata(data.args ?? {});
+        const sanitizedPayload = sanitizeRenderPayload(
+          {
+            args: processedArgs,
+            slots: data.slots ?? {}
+          },
+          sanitizationOptions
+        );
+
+        return container.renderToString(
+          patchedComponent as Parameters<typeof container.renderToString>[0],
+          {
+            props: sanitizedPayload.args,
+            slots: sanitizedPayload.slots
+          }
+        );
+      });
+    };
+
+    const resultPromise = renderQueue.then(executeRender, executeRender);
+
+    renderQueue = resultPromise.then(
+      () => undefined,
+      () => undefined
+    );
+
+    return resultPromise;
   };
 }
 
-/**
- * Wraps an Astro component factory to fix the createAstro calling convention mismatch
- * between Astro compiler v2 and the Astro 6 runtime.
- *
- * The compiled component calls result.createAstro($$Astro, $$props, $$slots) [3 args],
- * but the Astro 6 runtime's createResult defines createAstro(props, slots) [2 params].
- * This causes $$Astro to be captured as "props" and actual props to be lost.
- *
- * The wrapper intercepts the result object and patches its createAstro method to
- * handle both calling conventions.
- */
-function patchCreateAstroCompat(Component: any): any {
-  const wrapped = (result: any, props: any, slots: any) => {
-    if (result && result.createAstro) {
-      const origCreateAstro = result.createAstro;
-
-      result.createAstro = (...args: any[]) => {
-        if (args.length === 3) {
-          // Compiler v2 convention: ($$Astro, $$props, $$slots) → skip $$Astro
-          return origCreateAstro(args[1], args[2]);
+function patchCreateAstroCompat(component: unknown): AstroComponentFactory {
+  if (typeof component !== 'function') {
+    throw new Error('Expected Astro component factory to be a function.');
+  }
+
+  const originalComponent = component as AstroComponentFactory;
+  const wrapped = ((result: AstroCreateResult, props: unknown, slots: unknown) => {
+    if (result && typeof result.createAstro === 'function') {
+      const originalCreateAstro = result.createAstro;
+      const runtimeExpectsAstroGlobal = originalCreateAstro.length >= 3;
+
+      result.createAstro = (...args: unknown[]) => {
+        if (args.length === 3 && !runtimeExpectsAstroGlobal) {
+          return originalCreateAstro(args[1], args[2]);
         }
 
-        // Compiler v3 convention: ($$props, $$slots) → pass through
-        return origCreateAstro(...args);
+        return originalCreateAstro(...args);
       };
     }
 
-    return Component(result, props, slots);
-  };
+    return originalComponent(result, props, slots);
+  }) as AstroComponentFactory;
 
-  // Copy component factory metadata so the Container treats it as a valid Astro component
-  wrapped.isAstroComponentFactory = Component.isAstroComponentFactory;
-  wrapped.moduleId = Component.moduleId;
-  wrapped.propagation = Component.propagation;
+  wrapped.isAstroComponentFactory = originalComponent.isAstroComponentFactory;
+  wrapped.moduleId = originalComponent.moduleId;
+  wrapped.propagation = originalComponent.propagation;
 
   return wrapped;
 }
 
-/**
- * Recursively processes arguments to convert ImageMetadata objects to usable image URLs.
- * This allows Astro's Image component to work properly in Storybook by converting
- * optimized asset references to direct file paths.
- */
-async function processImageMetadata(args: Record<string, unknown>): Promise<Record<string, unknown>> {
+async function processImageMetadata(
+  args: Record<string, unknown>
+): Promise<Record<string, unknown>> {
   const processed: Record<string, unknown> = {};
-  
+
   for (const [key, value] of Object.entries(args)) {
     if (isImageMetadata(value)) {
-      // Convert ImageMetadata to a usable URL
       processed[key] = convertImageMetadataToUrl(value);
-    } else if (Array.isArray(value)) {
-      // Process arrays recursively
+
+      continue;
+    }
+
+    if (Array.isArray(value)) {
       processed[key] = await Promise.all(
-        value.map(async (item) => 
-          typeof item === 'object' && item !== null 
-            ? await processImageMetadata(item as Record<string, unknown>)
-            : item
-        )
+        value.map(async (item) => {
+          if (isImageMetadata(item)) {
+            return convertImageMetadataToUrl(item);
+          }
+
+          if (isRecord(item)) {
+            return processImageMetadata(item);
+          }
+
+          return item;
+        })
       );
-    } else if (typeof value === 'object' && value !== null) {
-      // Process nested objects recursively
-      processed[key] = await processImageMetadata(value as Record<string, unknown>);
-    } else {
-      processed[key] = value;
+
+      continue;
+    }
+
+    if (isRecord(value)) {
+      processed[key] = await processImageMetadata(value);
+
+      continue;
     }
+
+    processed[key] = value;
   }
-  
+
   return processed;
 }
 
-/**
- * Type guard to check if a value is an ImageMetadata object.
- * ImageMetadata objects typically have properties like src, width, height, format.
- */
-function isImageMetadata(value: unknown): value is Record<string, any> {
+function isImageMetadata(value: unknown): value is Record<string, unknown> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    'src' in value &&
-    typeof (value as any).src === 'string' &&
+    isRecord(value) &&
+    typeof value.src === 'string' &&
     ('width' in value || 'height' in value || 'format' in value)
   );
 }
 
-/**
- * Converts an ImageMetadata object to a usable URL for Storybook.
- * In a Storybook environment, we use the raw file path instead of optimized URLs.
- */
-function convertImageMetadataToUrl(imageMetadata: Record<string, any>): string {
-  // For Storybook, use the raw src path which should be the file path
-  // This bypasses Astro's image optimization which doesn't work in Storybook
-  return imageMetadata.src || imageMetadata.fsPath || String(imageMetadata);
+function convertImageMetadataToUrl(imageMetadata: Record<string, unknown>): string {
+  const src = imageMetadata.src;
+  const fsPath = imageMetadata.fsPath;
+
+  if (typeof src === 'string') {
+    return src;
+  }
+
+  if (typeof fsPath === 'string') {
+    return fsPath;
+  }
+
+  return String(imageMetadata);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
 }

package/src/module-mocks.ts

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export type StoryModuleMocks = Map<string, string>;
+
+const moduleMockStorage = new AsyncLocalStorage<StoryModuleMocks>();
+
+export async function withStoryModuleMocks<T>(
+  moduleMocks: StoryModuleMocks,
+  callback: () => Promise<T>
+): Promise<T> {
+  return moduleMockStorage.run(moduleMocks, callback);
+}
+
+export function resolveStoryModuleMock(specifier: string): string | undefined {
+  return moduleMockStorage.getStore()?.get(specifier);
+}

package/src/msw-helpers.ts

@@ -0,0 +1 @@
+export { http, HttpResponse } from 'msw';

package/src/msw.ts

@@ -0,0 +1,58 @@
+import type { RequestHandler } from 'msw';
+import { setupServer } from 'msw/node';
+
+type MswServer = ReturnType<typeof setupServer>;
+type MswServerListenOptions = Parameters<MswServer['listen']>[0];
+
+type MswState = {
+  server?: MswServer;
+  pendingUpdate?: Promise<void>;
+};
+
+type MswGlobalState = typeof globalThis & {
+  __storybookAstroMswState__?: MswState;
+};
+
+const defaultListenOptions: MswServerListenOptions = {
+  onUnhandledRequest: 'bypass'
+};
+
+export async function applyMswHandlers(handlers: RequestHandler[]): Promise<void> {
+  const state = getMswState();
+
+  if (state.pendingUpdate) {
+    await state.pendingUpdate;
+  }
+
+  const updatePromise = syncMswHandlers(handlers, state);
+
+  state.pendingUpdate = updatePromise;
+
+  try {
+    await updatePromise;
+  } finally {
+    state.pendingUpdate = undefined;
+  }
+}
+
+async function syncMswHandlers(handlers: RequestHandler[], state: MswState): Promise<void> {
+  if (!state.server) {
+    state.server = setupServer();
+    state.server.listen(defaultListenOptions);
+  }
+
+  state.server.resetHandlers(...handlers);
+}
+
+function getMswState(): MswState {
+  const globalState = globalThis as MswGlobalState;
+
+  if (!globalState.__storybookAstroMswState__) {
+    globalState.__storybookAstroMswState__ = {
+      server: undefined,
+      pendingUpdate: undefined
+    };
+  }
+
+  return globalState.__storybookAstroMswState__;
+}

package/src/preset.ts

@@ -3,6 +3,8 @@ import { vitePluginStorybookAstroMiddleware } from './viteStorybookAstroMiddlewa
 import { viteStorybookRendererFallbackPlugin } from './viteStorybookRendererFallbackPlugin.ts';
 import { vitePluginAstroComponentMarker } from './vitePluginAstroComponentMarker.ts';
 import { vitePluginAstroBuildPrerender } from './vitePluginAstroBuildPrerender.ts';
+import { vitePluginAstroVueFallback } from './vitePluginAstroVueFallback.ts';
+import { resolveSanitizationOptions } from './lib/sanitization.ts';
 import { mergeWithAstroConfig } from './vitePluginAstro.ts';
 
 export const core = {
@@ -10,7 +12,7 @@ export const core = {
   renderer: '@storybook-astro/renderer'
 };
 
-export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { presets }) => {
+export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { configType, presets }) => {
   const options = await presets.apply<FrameworkOptions>('frameworkOptions');
   const { vitePlugin: storybookAstroMiddlewarePlugin, viteConfig } =
     await vitePluginStorybookAstroMiddleware(options);
@@ -20,6 +22,11 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { pres
   }
 
   const integrations = options.integrations ?? [];
+  const resolveFrom = options.resolveFrom ?? process.cwd();
+  const mode = configType === 'DEVELOPMENT' ? 'development' : 'production';
+  const command = configType === 'DEVELOPMENT' ? 'serve' : 'build';
+
+  resolveSanitizationOptions(options.sanitization);
 
   config.plugins.push(
     storybookAstroMiddlewarePlugin,
@@ -27,7 +34,8 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { pres
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     vitePluginAstroComponentMarker() as any,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    vitePluginAstroBuildPrerender(integrations) as any,
+    vitePluginAstroBuildPrerender(options) as any,
+    vitePluginAstroVueFallback(),
     ...viteConfig.plugins
   );
 
@@ -49,7 +57,34 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { pres
     aliases['react-dom'] = 'react-dom';
   }
 
-  const finalConfig = await mergeWithAstroConfig(config, integrations);
+  const finalConfig = await mergeWithAstroConfig(config, integrations, resolveFrom, mode, command);
+
+  // Exclude @astrojs/vue from dependency optimization because it imports
+  // virtual modules that esbuild cannot resolve (virtual:@astrojs/vue/app).
+  // This must be done after mergeWithAstroConfig to avoid being overwritten.
+  if (!finalConfig.optimizeDeps) {
+    finalConfig.optimizeDeps = {};
+  }
+  if (!finalConfig.optimizeDeps.exclude) {
+    finalConfig.optimizeDeps.exclude = [];
+  }
+  if (!finalConfig.optimizeDeps.exclude.includes('@astrojs/vue')) {
+    finalConfig.optimizeDeps.exclude.push('@astrojs/vue');
+  }
+  // Mark Vue virtual modules as external so esbuild doesn't try to resolve them
+  if (!finalConfig.optimizeDeps.esbuildOptions) {
+    finalConfig.optimizeDeps.esbuildOptions = {};
+  }
+  if (!finalConfig.optimizeDeps.esbuildOptions.external) {
+    finalConfig.optimizeDeps.esbuildOptions.external = [];
+  }
+  const vueVirtualModules = ['virtual:@astrojs/vue/app', 'virtual:astro:vue-app'];
+
+  for (const mod of vueVirtualModules) {
+    if (!finalConfig.optimizeDeps.esbuildOptions.external.includes(mod)) {
+      finalConfig.optimizeDeps.esbuildOptions.external.push(mod);
+    }
+  }
 
   return finalConfig;
 };

package/src/rules-options.test.ts

@@ -0,0 +1,71 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { afterEach, describe, expect, test } from 'vitest';
+import { resolveRulesConfigFilePath } from './rules-options.ts';
+
+const createdDirs = new Set<string>();
+
+afterEach(async () => {
+  await Promise.all(
+    Array.from(createdDirs).map(async (directory) => {
+      await rm(directory, { recursive: true, force: true });
+      createdDirs.delete(directory);
+    })
+  );
+});
+
+async function createTempDirectory() {
+  const directory = await mkdtemp(join(tmpdir(), 'storybook-astro-story-rules-'));
+
+  createdDirs.add(directory);
+
+  return directory;
+}
+
+describe('resolveRulesConfigFilePath', () => {
+  test('returns undefined when story rules are not configured', () => {
+    expect(resolveRulesConfigFilePath(undefined)).toBeUndefined();
+  });
+
+  test('resolves a direct file path', async () => {
+    const directory = await createTempDirectory();
+    const configPath = join(directory, 'story-rules.ts');
+
+    await writeFile(configPath, 'export default { rules: [] };', 'utf-8');
+
+    expect(resolveRulesConfigFilePath('./story-rules.ts', directory)).toBe(configPath);
+  });
+
+  test('resolves extensionless config path', async () => {
+    const directory = await createTempDirectory();
+    const configPath = join(directory, 'story-rules.ts');
+
+    await writeFile(configPath, 'export default { rules: [] };', 'utf-8');
+
+    expect(resolveRulesConfigFilePath('./story-rules', directory)).toBe(configPath);
+  });
+
+  test('resolves directory config to index file', async () => {
+    const directory = await createTempDirectory();
+    const configDirectory = join(directory, 'story-rules');
+    const configPath = join(configDirectory, 'index.ts');
+
+    await mkdir(configDirectory, { recursive: true });
+    await writeFile(configPath, 'export default { rules: [] };', 'utf-8');
+
+    expect(resolveRulesConfigFilePath('./story-rules', directory)).toBe(configPath);
+  });
+
+  test('throws when the configured file does not exist', () => {
+    expect(() => resolveRulesConfigFilePath('./missing-rules', '/tmp')).toThrow(
+      'framework.options.storyRules config file was not found:'
+    );
+  });
+
+  test('throws when config path is empty', () => {
+    expect(() => resolveRulesConfigFilePath('   ')).toThrow(
+      'framework.options.storyRules config file path cannot be empty.'
+    );
+  });
+});

package/src/rules-options.ts

@@ -0,0 +1,87 @@
+import { existsSync, statSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+
+export type StoryRulesOptions =
+  | string
+  | {
+      configFile: string;
+    };
+
+export function resolveRulesConfigFilePath(
+  options?: StoryRulesOptions,
+  resolveFrom = process.cwd()
+): string | undefined {
+  if (options === undefined) {
+    return undefined;
+  }
+
+  const configFile = normalizeConfigFileOption(options);
+  const resolvedConfigFilePath = resolve(resolveFrom, configFile);
+  const normalizedConfigFilePath = resolveConfigFilePath(resolvedConfigFilePath);
+
+  if (!normalizedConfigFilePath) {
+    throw new Error(
+      `framework.options.storyRules config file was not found: ${resolvedConfigFilePath}. ` +
+        'Provide an existing path in framework.options.storyRules.'
+    );
+  }
+
+  return normalizedConfigFilePath;
+}
+
+function normalizeConfigFileOption(options: StoryRulesOptions): string {
+  const configFile =
+    typeof options === 'string'
+      ? options
+      : typeof options === 'object' && options !== null
+        ? options.configFile
+        : undefined;
+
+  if (typeof configFile !== 'string') {
+    throw new Error(
+      'framework.options.storyRules must be either a string path or an object with a string configFile.'
+    );
+  }
+
+  const normalizedConfigFile = configFile.trim();
+
+  if (!normalizedConfigFile) {
+    throw new Error('framework.options.storyRules config file path cannot be empty.');
+  }
+
+  return normalizedConfigFile;
+}
+
+function resolveConfigFilePath(filePath: string): string | undefined {
+  if (existsSync(filePath)) {
+    const fileStats = statSync(filePath);
+
+    if (fileStats.isFile()) {
+      return filePath;
+    }
+  }
+
+  if (extname(filePath)) {
+    return undefined;
+  }
+
+  const extensions = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'];
+
+  for (const extension of extensions) {
+    const candidateFilePath = `${filePath}${extension}`;
+
+    if (existsSync(candidateFilePath)) {
+      return candidateFilePath;
+    }
+  }
+
+  for (const extension of extensions) {
+    const candidateFilePath = resolve(filePath, `index${extension}`);
+
+    if (existsSync(candidateFilePath)) {
+      return candidateFilePath;
+    }
+  }
+
+  return undefined;
+}