@storybook-astro/framework 1.2.0 → 1.3.0-canary.2

package/src/astroImageService.ts

@@ -0,0 +1,57 @@
+export function ensureAstroPassthroughImageService() {
+  if (!globalThis.astroAsset) {
+    (globalThis as Record<string, unknown>).astroAsset = {};
+  }
+
+  (globalThis.astroAsset as Record<string, unknown>).imageService = {
+    propertiesToHash: ['src'],
+    validateOptions(options: Record<string, unknown>) {
+      return options;
+    },
+    getURL(options: { src: unknown }) {
+      const src = options.src;
+
+      if (
+        src != null &&
+        typeof src === 'object' &&
+        'src' in src &&
+        typeof (src as Record<string, unknown>).src === 'string'
+      ) {
+        return (src as Record<string, unknown>).src as string;
+      }
+
+      return typeof src === 'string' ? src : '';
+    },
+    getHTMLAttributes(options: Record<string, unknown>) {
+      const {
+        src,
+        width,
+        height,
+        format,
+        quality,
+        densities,
+        widths,
+        formats,
+        layout,
+        priority,
+        fit,
+        position,
+        background,
+        ...attrs
+      } = options;
+      const srcObject =
+        src != null && typeof src === 'object' ? (src as Record<string, unknown>) : null;
+
+      return {
+        ...attrs,
+        width: width ?? srcObject?.width,
+        height: height ?? srcObject?.height,
+        loading: (attrs.loading as string | undefined) ?? 'lazy',
+        decoding: (attrs.decoding as string | undefined) ?? 'async'
+      };
+    },
+    getSrcSet() {
+      return [];
+    }
+  };
+}

package/src/astroRenderHandler.ts

@@ -0,0 +1,205 @@
+import type { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import type { SanitizationOptions } from './lib/sanitization.ts';
+import { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';
+import { reviveDateStrings } from './lib/revive-dates.ts';
+import { runWithStoryRules, type ResolveRulesConfigModule } from './storyRulesRuntime.ts';
+import type { RenderStoryInput } from './types.ts';
+
+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 CreateAstroRenderHandlerOptions = {
+  container: Awaited<ReturnType<typeof AstroContainer.create>>;
+  sanitization?: SanitizationOptions;
+  rulesConfigFilePath?: string;
+  resolveRulesConfigModule?: ResolveRulesConfigModule;
+  loadModule: (id: string) => Promise<{ default: unknown }>;
+  invalidateModuleGraph?: () => void;
+};
+
+export function createAstroRenderHandler(options: CreateAstroRenderHandlerOptions) {
+  const sanitizationOptions = resolveSanitizationOptions(options.sanitization);
+  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 options.loadModule(componentId);
+
+      return patchCreateAstroCompat(component);
+    }
+
+    if (!componentCache.has(componentId)) {
+      componentCache.set(
+        componentId,
+        (async () => {
+          const { default: component } = await options.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) {
+      componentCache.delete(componentId);
+      throw error;
+    }
+  }
+
+  return async function handler(data: HandlerProps) {
+    const executeRender = async () => {
+      return runWithStoryRules(
+        {
+          story: data.story,
+          rulesConfigFilePath: options.rulesConfigFilePath,
+          resolveRulesConfigModule: options.resolveRulesConfigModule,
+          invalidateModuleGraph: options.invalidateModuleGraph
+        },
+        async (selectedRules) => {
+          const patchedComponent = await loadPatchedComponent(
+            data.component,
+            selectedRules.moduleMocks.size === 0
+          );
+          const processedArgs = await processImageMetadata(data.args ?? {});
+          const revivedArgs = reviveDateStrings(processedArgs);
+          const sanitizedPayload = sanitizeRenderPayload(
+            {
+              args: revivedArgs,
+              slots: data.slots ?? {}
+            },
+            sanitizationOptions
+          );
+
+          return options.container.renderToString(
+            patchedComponent as Parameters<typeof options.container.renderToString>[0],
+            {
+              props: sanitizedPayload.args,
+              slots: sanitizedPayload.slots
+            }
+          );
+        }
+      );
+    };
+
+    const resultPromise = renderQueue.then(executeRender, executeRender);
+
+    renderQueue = resultPromise.then(
+      () => undefined,
+      () => undefined
+    );
+
+    return resultPromise;
+  };
+}
+
+export 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]);
+        }
+
+        return originalCreateAstro(...args);
+      };
+    }
+
+    return originalComponent(result, props, slots);
+  }) as AstroComponentFactory;
+
+  wrapped.isAstroComponentFactory = originalComponent.isAstroComponentFactory;
+  wrapped.moduleId = originalComponent.moduleId;
+  wrapped.propagation = originalComponent.propagation;
+
+  return wrapped;
+}
+
+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)) {
+      // Keep ImageMetadata as an object so Astro's image pipeline still
+      // recognizes it as an imported image and skips local path validation.
+      processed[key] = value;
+
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      processed[key] = await Promise.all(
+        value.map(async (item) => {
+          if (isImageMetadata(item)) {
+            return item;
+          }
+
+          if (isRecord(item)) {
+            return processImageMetadata(item);
+          }
+
+          return item;
+        })
+      );
+
+      continue;
+    }
+
+    if (isRecord(value)) {
+      processed[key] = await processImageMetadata(value);
+
+      continue;
+    }
+
+    processed[key] = value;
+  }
+
+  return processed;
+}
+
+function isImageMetadata(value: unknown): value is Record<string, unknown> {
+  return (
+    isRecord(value) &&
+    typeof value.src === 'string' &&
+    ('width' in value || 'height' in value || 'format' in value)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/importAstroConfig.ts

@@ -7,5 +7,5 @@ export async function importAstroConfig(resolveFrom: string) {
     paths: [resolveFrom]
   });
 
-  return import(pathToFileURL(astroConfigEntrypoint).href);
+  return import(/* @vite-ignore */ pathToFileURL(astroConfigEntrypoint).href);
 }

package/src/index.ts

@@ -44,6 +44,8 @@ export type {
 } from './types.ts';
 export type {
   StoryRuleCleanup,
+  StoryRuleMock,
+  StoryRuleMockFactory,
   StoryRule,
   StoryRulesConfig,
   StoryRuleSelection,

package/src/integrations/alpine.ts

@@ -5,6 +5,7 @@ export type Options = Record<string, unknown>;
 
 export class AlpineIntegration implements Integration {
   readonly name = 'alpine';
+  readonly factoryName = 'alpinejs';
   readonly dependencies = [
     '@astrojs/alpinejs',
     'alpinejs'

package/src/integrations/base.ts

@@ -13,6 +13,12 @@ export type RendererDeclaration = {
 
 export abstract class Integration {
   abstract readonly name: string;
+  // Identifier used to import this integration's factory from
+  // `@storybook-astro/framework/integrations` when generating the server
+  // runtime module. Defaults to `name` for integrations whose public name
+  // matches their factory export. Override when they diverge (e.g. Alpine's
+  // `name` is "alpine" but its factory export is `alpinejs`).
+  readonly factoryName?: string;
   abstract readonly dependencies: string[];
   abstract readonly options: Record<string | number | symbol, unknown>;
   abstract readonly renderer: RendererDeclaration;

package/src/lib/revive-dates.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'vitest';
+import { reviveDateStrings } from './revive-dates.ts';
+
+describe('reviveDateStrings', () => {
+  test('converts an ISO 8601 date string to a Date object', () => {
+    const args = { pubDate: '2025-04-12T00:00:00.000Z' };
+    const result = reviveDateStrings(args);
+
+    expect(result.pubDate).toBeInstanceOf(Date);
+    expect((result.pubDate as Date).toISOString()).toBe('2025-04-12T00:00:00.000Z');
+  });
+
+  test('converts dates nested inside objects', () => {
+    const args = {
+      post: {
+        data: {
+          pubDate: '2025-04-12T00:00:00.000Z'
+        }
+      }
+    };
+    const result = reviveDateStrings(args);
+
+    expect((result.post as Record<string, unknown>)).toMatchObject({
+      data: {
+        pubDate: expect.any(Date)
+      }
+    });
+  });
+
+  test('converts dates inside arrays', () => {
+    const args = {
+      posts: [
+        { pubDate: '2025-04-12T00:00:00.000Z' },
+        { pubDate: '2025-03-08T00:00:00.000Z' }
+      ]
+    };
+    const result = reviveDateStrings(args);
+    const posts = result.posts as Array<{ pubDate: Date }>;
+
+    expect(posts[0].pubDate).toBeInstanceOf(Date);
+    expect(posts[1].pubDate).toBeInstanceOf(Date);
+    expect(posts[0].pubDate.toISOString()).toBe('2025-04-12T00:00:00.000Z');
+    expect(posts[1].pubDate.toISOString()).toBe('2025-03-08T00:00:00.000Z');
+  });
+
+  test('leaves non-date strings untouched', () => {
+    const args = {
+      title: 'Hello World',
+      description: 'A post about dates',
+      empty: ''
+    };
+    const result = reviveDateStrings(args);
+
+    expect(result.title).toBe('Hello World');
+    expect(result.description).toBe('A post about dates');
+    expect(result.empty).toBe('');
+  });
+
+  test('leaves date-only strings untouched (no time component)', () => {
+    const args = { date: '2025-04-12' };
+    const result = reviveDateStrings(args);
+
+    expect(result.date).toBe('2025-04-12');
+  });
+
+  test('leaves partial ISO strings untouched', () => {
+    const args = {
+      noMillis: '2025-04-12T00:00:00Z',
+      withOffset: '2025-04-12T00:00:00.000+00:00',
+      dateOnly: '2025-04-12'
+    };
+    const result = reviveDateStrings(args);
+
+    expect(result.noMillis).toBe('2025-04-12T00:00:00Z');
+    expect(result.withOffset).toBe('2025-04-12T00:00:00.000+00:00');
+    expect(result.dateOnly).toBe('2025-04-12');
+  });
+
+  test('preserves non-string values', () => {
+    const args = {
+      count: 42,
+      active: true,
+      missing: null,
+      tags: ['a', 'b']
+    };
+    const result = reviveDateStrings(args);
+
+    expect(result.count).toBe(42);
+    expect(result.active).toBe(true);
+    expect(result.missing).toBe(null);
+    expect(result.tags).toEqual(['a', 'b']);
+  });
+
+  test('handles an empty args object', () => {
+    expect(reviveDateStrings({})).toEqual({});
+  });
+
+  test('round-trips a Date through JSON serialization', () => {
+    const original = new Date('2025-06-04T14:30:00.000Z');
+    const serialized = JSON.parse(JSON.stringify({ date: original })) as Record<string, unknown>;
+    const result = reviveDateStrings(serialized);
+
+    expect(result.date).toBeInstanceOf(Date);
+    expect((result.date as Date).getTime()).toBe(original.getTime());
+  });
+});

package/src/lib/revive-dates.ts

@@ -0,0 +1,51 @@
+/**
+ * Revives Date objects that were lost during JSON serialization.
+ *
+ * When story args travel over Vite HMR (dev) or HTTP (server mode), Date
+ * values are serialized by JSON.stringify into ISO 8601 strings like
+ * "2025-04-12T00:00:00.000Z". This function walks the args tree and
+ * converts those strings back into Date objects so Astro components
+ * receive the types they expect.
+ *
+ * Only the exact format produced by Date.toJSON() is matched
+ * (YYYY-MM-DDTHH:mm:ss.sssZ) to minimize false positives.
+ */
+
+// Matches the exact output of Date.toJSON() / JSON.stringify(date).
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+export function reviveDateStrings(args: Record<string, unknown>): Record<string, unknown> {
+  const revived: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(args)) {
+    revived[key] = reviveValue(value);
+  }
+
+  return revived;
+}
+
+function reviveValue(value: unknown): unknown {
+  if (typeof value === 'string' && ISO_DATE_PATTERN.test(value)) {
+    const date = new Date(value);
+
+    if (!Number.isNaN(date.getTime())) {
+      return date;
+    }
+
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(reviveValue);
+  }
+
+  if (isRecord(value)) {
+    return reviveDateStrings(value);
+  }
+
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}