@storybook-astro/framework 0.1.0-beta.9 → 1.0.1

package/src/testing.ts

@@ -1,254 +1 @@
-/**
- * Testing utilities for @storybook-astro/framework
- *
- * Provides test helpers for validating Storybook stories in Vitest,
- * and Vite plugins needed for the test environment.
- *
- * @example
- * ```ts
- * // In a test file:
- * import { composeStories } from '@storybook-astro/framework';
- * import { testStoryRenders, testStoryComposition } from '@storybook-astro/framework/testing';
- * import * as stories from './Card.stories.jsx';
- *
- * const { Default } = composeStories(stories);
- * testStoryComposition('Default', Default);
- * testStoryRenders('Card Default', Default);
- * ```
- *
- * @example
- * ```ts
- * // In vitest.config.ts:
- * import { cjsInteropPlugin } from '@storybook-astro/framework/testing';
- * import { defineConfig } from 'vitest/config';
- *
- * export default defineConfig({
- *   plugins: [cjsInteropPlugin()],
- *   // ...
- * });
- * ```
- */
-
-// eslint-disable-next-line n/no-extraneous-import
-import { test, expect } from 'vitest';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import type { Plugin } from 'vite';
-
-// ---------------------------------------------------------------------------
-// Test helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Registers a Vitest test that validates a composed story can render.
- *
- * The test will:
- * - Pass if the component renders successfully in Storybook
- * - Pass if the Storybook runtime is not available (expected in Vitest)
- * - Pass if a framework hits an SSR-only limitation (e.g. Solid)
- * - Fail if the component has a broken framework integration or missing renderer
- *
- * @param storyName - Display name for the test
- * @param story - A composed story returned by `composeStories`
- */
-export function testStoryRenders(storyName: string, story: any) {
-  test(`${storyName} renders in Storybook`, async () => {
-    expect(story).toBeDefined();
-    expect(typeof story).toBe('function');
-
-    try {
-      // First try calling the story directly - this will use our custom render function
-      // which can detect broken framework integrations immediately
-      const directResult = story();
-
-      // If direct call succeeds, try the full Storybook run method
-      const result = await story.run?.() || directResult;
-
-      // If we get here, the component should have rendered successfully
-      expect(result).toBeDefined();
-
-      // For Astro components, check that we have component and args
-      if (result.component) {
-        expect(result.component).toBeDefined();
-        expect(result.args).toBeDefined();
-      }
-
-      console.warn(`✓ ${storyName} rendered successfully`);
-
-    } catch (error: any) {
-      const errorMessage = error.message;
-
-      // Check if this is an expected error when Storybook is not running
-      if (errorMessage.includes('renderToCanvas is not a function')) {
-        // This indicates the component is properly configured but Storybook runtime isn't available
-        // This is acceptable for Astro components that work in Storybook
-        console.warn(`✓ ${storyName} is properly configured (Storybook runtime not available)`);
-
-        return;
-      }
-
-      // SSR limitation: some framework components (e.g. Solid) are compiled in
-      // SSR mode for the test environment. Client-only APIs are unavailable
-      // during story.run(), but the component works in Storybook's browser.
-      if (errorMessage.includes('Client-only API called on the server side')) {
-        console.warn(`✓ ${storyName} is properly configured (SSR-only test limitation)`);
-
-        return;
-      }
-
-      // Check for renderer not found errors (indicates broken integration)
-      if (errorMessage.includes('Renderer') && errorMessage.includes('not found')) {
-        console.error(`✗ ${storyName} failed: ${errorMessage}`);
-        throw new Error(`${storyName} has a broken framework integration: ${errorMessage}`);
-      }
-
-      // Check for missing renderer parameter
-      if (errorMessage.includes('no renderer is specified')) {
-        console.error(`✗ ${storyName} failed: ${errorMessage}`);
-        throw new Error(`${storyName} is missing renderer parameter: ${errorMessage}`);
-      }
-
-      // Any other error indicates a real problem with the component
-      console.error(`✗ ${storyName} failed with unexpected error:`, error);
-      throw new Error(`${storyName} failed to render: ${errorMessage}`);
-    }
-  });
-}
-
-/**
- * Registers a Vitest test that checks basic story composition.
- *
- * Validates that the story can be imported, composed, and has the
- * expected name. Optionally checks that args match expected values.
- *
- * @param storyName - Expected `story.storyName` value
- * @param story - A composed story returned by `composeStories`
- * @param expectedArgs - Optional args to assert with `toEqual`
- */
-export function testStoryComposition(storyName: string, story: any, expectedArgs?: any) {
-  test(`${storyName} can be composed`, () => {
-    expect(story).toBeDefined();
-    expect(typeof story).toBe('function');
-    expect(story.storyName).toBe(storyName);
-
-    if (expectedArgs) {
-      expect(story.args).toEqual(expectedArgs);
-    }
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Vite plugins for testing
-// ---------------------------------------------------------------------------
-
-/**
- * Vite plugin that wraps CJS modules with ESM-compatible shims.
- *
- * Vite 6's ESM module runner cannot evaluate raw CommonJS modules that use
- * `module.exports` or `exports`. This plugin detects CJS modules in
- * node_modules during transform and wraps them so they work in ESM context.
- *
- * Use this in your `vitest.config.ts` plugins array when testing with
- * Astro 6 and Vite 6+.
- *
- * @example
- * ```ts
- * import { cjsInteropPlugin } from '@storybook-astro/framework/testing';
- *
- * export default defineConfig({
- *   plugins: [cjsInteropPlugin()],
- * });
- * ```
- */
-export function cjsInteropPlugin(): Plugin {
-  return {
-    name: 'cjs-esm-interop',
-    enforce: 'pre',
-    resolveId(id) {
-      // When Vite resolves a bare import in SSR/test context, redirect
-      // packages that have ESM entry points to those entries instead of
-      // their CJS "main" or "require" entries.
-      if (id.startsWith('.') || id.startsWith('/') || id.startsWith('\0') || id.includes('node_modules')) {return;}
-
-      // Find the package's node_modules directory
-      const parts = id.split('/');
-      const pkgName = id.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
-      const subpath = parts.slice(pkgName.split('/').length).join('/');
-
-      // Only redirect the main entry (no subpath or common subpaths)
-      if (subpath && !['server-renderer', 'server', 'client'].includes(subpath)) {return;}
-
-      try {
-        // Find the package.json
-        const nmDir = join(process.cwd(), 'node_modules', pkgName);
-        const pkgJsonPath = join(nmDir, 'package.json');
-
-        if (!existsSync(pkgJsonPath)) {return;}
-
-        const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-
-        // Check for ESM entry in exports map
-        const exportKey = subpath ? `./${subpath}` : '.';
-        const exportEntry = pkgJson.exports?.[exportKey];
-
-        if (exportEntry) {
-          const importEntry = exportEntry.import;
-
-          if (importEntry) {
-            const esmPath = typeof importEntry === 'string'
-              ? importEntry
-              : importEntry.default || importEntry.node;
-
-            if (esmPath) {
-              const resolved = join(nmDir, esmPath);
-
-              if (existsSync(resolved)) {
-                return resolved;
-              }
-            }
-          }
-        }
-
-        // Fallback: check the "module" field
-        if (!subpath && pkgJson.module) {
-          const resolved = join(nmDir, pkgJson.module);
-
-          if (existsSync(resolved)) {
-            return resolved;
-          }
-        }
-      } catch {
-        // Ignore resolution errors
-      }
-    },
-    transform(code, id) {
-      // Only transform node_modules files
-      if (!id.includes('node_modules')) {return;}
-      // Skip virtual modules
-      if (id.startsWith('\0')) {return;}
-      // Skip files that already use ESM exports
-      if (/\bexport\s+(default|const|let|var|function|class|\{|\*)/.test(code)) {return;}
-      // Only wrap files that use CJS patterns
-      if (!code.includes('module.exports') && !code.includes('exports.')) {return;}
-
-      const dirPath = id.substring(0, id.lastIndexOf('/'));
-      const fileName = id;
-
-      
-return {
-        code: [
-          'import { createRequire as __createRequire } from "module";',
-          `var __require = __createRequire("file://${dirPath}/");`,
-          'var module = { exports: {} };',
-          'var exports = module.exports;',
-          'function require(id) { return __require(id); }',
-          `var __dirname = ${JSON.stringify(dirPath)};`,
-          `var __filename = ${JSON.stringify(fileName)};`,
-          code,
-          'export default module.exports;',
-        ].join('\n'),
-        map: null,
-      };
-    }
-  };
-}
+export * from './testing/index.ts';

package/src/types.ts

@@ -1,18 +1,30 @@
 import type { CompatibleString, Options } from 'storybook/internal/types';
 import type { InlineConfig } from 'vite';
 import type { Integration } from './integrations/index.ts';
+import type { SanitizationOptions } from './lib/sanitization.ts';
+import type { StoryRulesOptions } from './rules-options.ts';
 
 type FrameworkName = CompatibleString<'@storybook-astro/framework'>;
 
-export type { Integration };
+export type { Integration, SanitizationOptions, StoryRulesOptions };
+
+export type RenderStoryInput = {
+  id: string;
+  title?: string;
+  name?: string;
+};
+
 export type FrameworkOptions = {
-  integrations: Integration[];
+  integrations?: Integration[];
+  sanitization?: SanitizationOptions;
+  storyRules?: StoryRulesOptions;
+  resolveFrom?: string;
 };
 
 type StorybookConfigFramework = {
   framework: {
     name: FrameworkName;
-    options: FrameworkOptions;
+    options?: FrameworkOptions;
   };
 };
 
@@ -21,5 +33,5 @@ export type StorybookConfig = StorybookConfigFramework;
 type ViteFinal = (config: InlineConfig, options: Options) => InlineConfig | Promise<InlineConfig>;
 
 export type StorybookConfigVite = {
-    viteFinal?: ViteFinal;
+  viteFinal?: ViteFinal;
 };

package/src/virtual.d.ts

@@ -2,6 +2,7 @@ declare module 'virtual:astro-container-renderers' {
   import type { experimental_AstroContainer as AstroContainer } from 'astro/container';
 
   export function addRenderers(container: AstroContainer): void;
+  export function resolveClientModules(specifier: string): string | undefined;
 }
 
-declare module 'virtual:storybook-renderer-fallback' {}
+declare module 'virtual:storybook-renderer-fallback' {}

package/src/vite/createVirtualModulePlugin.test.ts

@@ -0,0 +1,80 @@
+import type { PluginOption } from 'vite';
+import { describe, expect, test, vi } from 'vitest';
+import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+
+function getPlugin(pluginOption: PluginOption) {
+  if (Array.isArray(pluginOption)) {
+    throw new Error('Expected a single plugin object, but got a plugin array.');
+  }
+
+  if (!pluginOption || typeof pluginOption !== 'object') {
+    throw new Error('Expected plugin option to be an object.');
+  }
+
+  return pluginOption;
+}
+
+function getHookHandler<T extends (...args: unknown[]) => unknown>(hook: unknown): T {
+  if (typeof hook === 'function') {
+    return hook as T;
+  }
+
+  if (
+    typeof hook === 'object' &&
+    hook !== null &&
+    'handler' in hook &&
+    typeof (hook as { handler?: unknown }).handler === 'function'
+  ) {
+    return (hook as { handler: T }).handler;
+  }
+
+  throw new Error('Expected hook to be a function or an object with a handler function.');
+}
+
+describe('createVirtualModulePlugin', () => {
+  test('resolves configured virtual module id with a null-byte prefix', () => {
+    const pluginOption = createVirtualModulePlugin({
+      pluginName: 'test:virtual-module',
+      virtualModuleId: 'virtual:test-module',
+      load: () => 'export default true;'
+    });
+    const plugin = getPlugin(pluginOption);
+    const resolveId = getHookHandler<(id: string) => string | undefined>(plugin.resolveId);
+
+    expect(plugin.name).toBe('test:virtual-module');
+    expect(resolveId('virtual:test-module')).toBe('\0virtual:test-module');
+    expect(resolveId('virtual:other-module')).toBeUndefined();
+  });
+
+  test('loads module content only for the resolved virtual module id', async () => {
+    const load = vi.fn(() => 'export const message = "hello";');
+    const pluginOption = createVirtualModulePlugin({
+      pluginName: 'test:virtual-module',
+      virtualModuleId: 'virtual:test-module',
+      load
+    });
+    const plugin = getPlugin(pluginOption);
+    const loadModule = getHookHandler<(id: string) => Promise<string | undefined>>(plugin.load);
+
+    const result = await loadModule('\0virtual:test-module');
+
+    expect(result).toBe('export const message = "hello";');
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(load).toHaveBeenCalledWith('\0virtual:test-module');
+
+    await expect(loadModule('virtual:test-module')).resolves.toBeUndefined();
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  test('supports asynchronous virtual module loaders', async () => {
+    const pluginOption = createVirtualModulePlugin({
+      pluginName: 'test:virtual-module',
+      virtualModuleId: 'virtual:test-module',
+      load: async () => 'export default "async";'
+    });
+    const plugin = getPlugin(pluginOption);
+    const loadModule = getHookHandler<(id: string) => Promise<string | undefined>>(plugin.load);
+
+    await expect(loadModule('\0virtual:test-module')).resolves.toBe('export default "async";');
+  });
+});

package/src/vite/createVirtualModulePlugin.ts

@@ -0,0 +1,25 @@
+import type { PluginOption } from 'vite';
+
+type CreateVirtualModulePluginOptions = {
+  pluginName: string;
+  virtualModuleId: string;
+  load: (id: string) => string | Promise<string> | undefined;
+};
+
+export function createVirtualModulePlugin(options: CreateVirtualModulePluginOptions): PluginOption {
+  const resolvedVirtualModuleId = `\0${options.virtualModuleId}`;
+
+  return {
+    name: options.pluginName,
+    resolveId(id) {
+      if (id === options.virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    async load(id) {
+      if (id === resolvedVirtualModuleId) {
+        return options.load(id);
+      }
+    }
+  } satisfies PluginOption;
+}

package/src/viteAstroContainerRenderersPlugin.ts

@@ -1,35 +1,69 @@
 import type { Integration } from './integrations/index.ts';
+import { createVirtualModulePlugin } from './vite/createVirtualModulePlugin.ts';
 
-export function viteAstroContainerRenderersPlugin(integrations: Integration[]) {
+type PluginOptions = {
+  mode?: 'development' | 'production';
+  staticModuleMap?: Record<string, string>;
+};
+
+export function viteAstroContainerRenderersPlugin(
+  integrations: Integration[],
+  options: PluginOptions = {}
+) {
   const safeIntegrations = integrations ?? [];
-  const name = 'astro-container-renderers';
-  const virtualModuleId = `virtual:${name}`;
-  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
-
-  return {
-    name,
-
-    resolveId(id: string) {
-      if (id === virtualModuleId) {
-        return resolvedVirtualModuleId;
-      }
-    },
-
-    load(id: string) {
-      if (id === resolvedVirtualModuleId) {
-        const importStatements = buildImportStatements(safeIntegrations);
-
-        const code = `
-          ${importStatements}
-          export function addRenderers(container) {
-            ${safeIntegrations.map((integration) => buildServerRenderer(integration) + '\n' + buildClientRenderer(integration)).join('\n')}
+  const mode = options.mode ?? 'development';
+  const staticModuleMap = options.staticModuleMap ?? {};
+
+  return createVirtualModulePlugin({
+    pluginName: 'storybook-astro:container-renderers',
+    virtualModuleId: 'virtual:astro-container-renderers',
+    load() {
+      const importStatements = buildImportStatements(safeIntegrations);
+      const clientResolvers =
+        mode === 'development'
+          ? safeIntegrations
+              .filter((integration) => typeof integration.resolveClient === 'function')
+              .map((integration) =>
+                integration.resolveClient.toString().replace(/^resolveClient/, 'function')
+              )
+              .join(',\n')
+          : '';
+
+      return `
+        ${importStatements}
+
+        export function addRenderers(container) {
+          ${safeIntegrations.map((integration) => buildServerRenderer(integration) + '\n' + buildClientRenderer(integration)).join('\n')}
+        }
+
+        const staticClientModules = ${JSON.stringify(staticModuleMap, null, 2)};
+
+        const clientModulesResolvers = [
+          ${clientResolvers}
+        ];
+
+        export function resolveClientModules(specifier) {
+          if (Object.hasOwn(staticClientModules, specifier)) {
+            return staticClientModules[specifier];
+          }
+
+          const normalizedSpecifier = specifier.replace(/\\\\/g, '/').replace(/\\?.*$/, '');
+
+          if (Object.hasOwn(staticClientModules, normalizedSpecifier)) {
+            return staticClientModules[normalizedSpecifier];
           }
-        `;
 
-        return code;
-      }
+          for (const resolver of clientModulesResolvers) {
+            const resolution = resolver(specifier);
+
+            if (resolution) {
+              return resolution;
+            }
+          }
+        }
+      `;
     }
-  };
+  });
 }
 
 function buildImportStatements(integrations: Integration[]) {

package/src/vitePluginAstro.ts

@@ -1,5 +1,6 @@
 import { mergeConfig, type InlineConfig } from 'vite';
 import type { Integration } from './integrations/index.ts';
+import { importAstroConfig } from './importAstroConfig.ts';
 
 const ASTRO_PLUGINS_THAT_ARE_SUPPOSEDLY_NOT_NEEDED_IN_STORYBOOK = [
   '@astro/plugin-actions',
@@ -27,8 +28,14 @@ const ASTRO_PLUGINS_THAT_ARE_SUPPOSEDLY_NOT_NEEDED_IN_STORYBOOK = [
   'astro:vite-plugin-file-url'
 ];
 
-export async function mergeWithAstroConfig(config: InlineConfig, integrations: Integration[] = []) {
-  const { getViteConfig } = await import('astro/config');
+export async function mergeWithAstroConfig(
+  config: InlineConfig,
+  integrations: Integration[] = [],
+  resolveFrom = process.cwd(),
+  mode = 'development',
+  command: 'build' | 'serve' = 'serve'
+) {
+  const { getViteConfig } = await importAstroConfig(resolveFrom);
   const safeIntegrations = integrations ?? [];
 
   const astroConfig = await getViteConfig(
@@ -36,12 +43,12 @@ export async function mergeWithAstroConfig(config: InlineConfig, integrations: I
     {
       configFile: false,
       integrations: await Promise.all(
-        safeIntegrations.map((integration) => integration.loadIntegration())
+        safeIntegrations.map((integration) => integration.loadIntegration(resolveFrom))
       )
     }
   )({
-    mode: 'development',
-    command: 'serve'
+    mode,
+    command
   });
 
   const filteredPlugins = astroConfig