@useavalon/avalon 0.1.11 → 0.1.13

package/src/vite-plugin/errors.ts

@@ -1,127 +1,127 @@
-/**
- * Error Classes for Avalon Vite Plugin
- *
- * This module provides custom error classes for configuration and integration errors.
- * These errors include contextual information to help developers quickly identify
- * and fix issues.
- */
-
-/**
- * Thrown when configuration is invalid
- *
- * This error includes the specific field name and value that caused the error,
- * making it easier to identify and fix configuration issues.
- *
- * @example
- * ```ts
- * throw new AvalonConfigError(
- *   "must be a valid directory path",
- *   "islandsDir",
- *   123 // invalid value - should be a string
- * );
- * // Error: Avalon configuration error in 'islandsDir': must be a valid directory path
- * // Received value: 123
- * ```
- */
-export class AvalonConfigError extends Error {
-  /**
-   * The name of the configuration field that caused the error
-   */
-  public readonly field: string;
-
-  /**
-   * The invalid value that was provided
-   */
-  public readonly value: unknown;
-
-  constructor(message: string, field: string, value: unknown) {
-    const valueStr = formatValue(value);
-    super(`Avalon configuration error in '${field}': ${message}\nReceived value: ${valueStr}`);
-    this.name = "AvalonConfigError";
-    this.field = field;
-    this.value = value;
-
-    // Maintains proper stack trace for where error was thrown (V8 engines)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, AvalonConfigError);
-    }
-  }
-}
-
-/**
- * Thrown when an integration fails to load or has an invalid name
- *
- * This error includes the integration name and optionally the underlying cause,
- * making it easier to diagnose integration loading issues.
- *
- * @example
- * ```ts
- * throw new IntegrationError(
- *   "Failed to activate integration. Is @useavalon/react installed?",
- *   "react",
- *   originalError
- * );
- * // Error: Integration 'react': Failed to activate integration. Is @useavalon/react installed?
- * ```
- */
-export class IntegrationError extends Error {
-  /**
-   * The name of the integration that caused the error
-   */
-  public readonly integrationName: string;
-
-  /**
-   * The original error that caused this error, if any
-   */
-  public readonly originalCause?: Error;
-
-  constructor(message: string, integrationName: string, originalCause?: Error) {
-    super(`Integration '${integrationName}': ${message}`, { cause: originalCause });
-    this.name = "IntegrationError";
-    this.integrationName = integrationName;
-    this.originalCause = originalCause;
-
-    // Maintains proper stack trace for where error was thrown (V8 engines)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, IntegrationError);
-    }
-  }
-}
-
-/**
- * Format a value for display in error messages
- *
- * @param value - The value to format
- * @returns A string representation of the value
- */
-function formatValue(value: unknown): string {
-  if (value === undefined) {
-    return "undefined";
-  }
-  if (value === null) {
-    return "null";
-  }
-  if (typeof value === "string") {
-    return `"${value}"`;
-  }
-  if (typeof value === "function") {
-    return "[Function]";
-  }
-  if (Array.isArray(value)) {
-    if (value.length === 0) {
-      return "[]";
-    }
-    if (value.length <= 3) {
-      return `[${value.map(formatValue).join(", ")}]`;
-    }
-    return `[${value.slice(0, 3).map(formatValue).join(", ")}, ... (${value.length} items)]`;
-  }
-  if (typeof value === "object") {
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return "[Circular]";
-    }
-  }
-  return String(value as string | number | boolean | bigint | symbol);
-}
+/**
+ * Error Classes for Avalon Vite Plugin
+ *
+ * This module provides custom error classes for configuration and integration errors.
+ * These errors include contextual information to help developers quickly identify
+ * and fix issues.
+ */
+
+/**
+ * Thrown when configuration is invalid
+ *
+ * This error includes the specific field name and value that caused the error,
+ * making it easier to identify and fix configuration issues.
+ *
+ * @example
+ * ```ts
+ * throw new AvalonConfigError(
+ *   "must be a valid directory path",
+ *   "islandsDir",
+ *   123 // invalid value - should be a string
+ * );
+ * // Error: Avalon configuration error in 'islandsDir': must be a valid directory path
+ * // Received value: 123
+ * ```
+ */
+export class AvalonConfigError extends Error {
+  /**
+   * The name of the configuration field that caused the error
+   */
+  public readonly field: string;
+
+  /**
+   * The invalid value that was provided
+   */
+  public readonly value: unknown;
+
+  constructor(message: string, field: string, value: unknown) {
+    const valueStr = formatValue(value);
+    super(`Avalon configuration error in '${field}': ${message}\nReceived value: ${valueStr}`);
+    this.name = "AvalonConfigError";
+    this.field = field;
+    this.value = value;
+
+    // Maintains proper stack trace for where error was thrown (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AvalonConfigError);
+    }
+  }
+}
+
+/**
+ * Thrown when an integration fails to load or has an invalid name
+ *
+ * This error includes the integration name and optionally the underlying cause,
+ * making it easier to diagnose integration loading issues.
+ *
+ * @example
+ * ```ts
+ * throw new IntegrationError(
+ *   "Failed to activate integration. Is @useavalon/react installed?",
+ *   "react",
+ *   originalError
+ * );
+ * // Error: Integration 'react': Failed to activate integration. Is @useavalon/react installed?
+ * ```
+ */
+export class IntegrationError extends Error {
+  /**
+   * The name of the integration that caused the error
+   */
+  public readonly integrationName: string;
+
+  /**
+   * The original error that caused this error, if any
+   */
+  public readonly originalCause?: Error;
+
+  constructor(message: string, integrationName: string, originalCause?: Error) {
+    super(`Integration '${integrationName}': ${message}`, { cause: originalCause });
+    this.name = "IntegrationError";
+    this.integrationName = integrationName;
+    this.originalCause = originalCause;
+
+    // Maintains proper stack trace for where error was thrown (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, IntegrationError);
+    }
+  }
+}
+
+/**
+ * Format a value for display in error messages
+ *
+ * @param value - The value to format
+ * @returns A string representation of the value
+ */
+function formatValue(value: unknown): string {
+  if (value === undefined) {
+    return "undefined";
+  }
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "string") {
+    return `"${value}"`;
+  }
+  if (typeof value === "function") {
+    return "[Function]";
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return "[]";
+    }
+    if (value.length <= 3) {
+      return `[${value.map(formatValue).join(", ")}]`;
+    }
+    return `[${value.slice(0, 3).map(formatValue).join(", ")}, ... (${value.length} items)]`;
+  }
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return "[Circular]";
+    }
+  }
+  return String(value as string | number | boolean | bigint | symbol);
+}

package/src/vite-plugin/image-optimization.ts

@@ -1,156 +1,156 @@
-/**
- * Image Optimization Plugin for Avalon
- *
- * Wraps vite-imagetools to provide automatic image optimization with
- * sensible defaults for responsive images, modern formats, and srcset generation.
- *
- * Features:
- * - Automatic WebP/AVIF conversion
- * - Responsive srcset generation at multiple breakpoints
- * - Metadata stripping for privacy
- * - JSX component output for easy usage in islands
- *
- * Usage in components:
- * ```tsx
- * // Basic - returns optimized URL
- * import heroImg from './hero.jpg?w=800&format=webp';
- *
- * // With srcset for responsive images
- * import heroImg from './hero.jpg?w=400;800;1200&format=webp&as=srcset';
- *
- * // As JSX component (like Qwik's ?jsx)
- * import HeroImage from './hero.jpg?w=1200&jsx';
- * <HeroImage alt="Hero" />
- * ```
- */
-
-import type { Plugin } from "vite";
-import type { ResolvedImageConfig } from "./types.ts";
-import { createRequire } from "node:module";
-import { join } from "node:path";
-
-/**
- * Creates the vite-imagetools plugin with Avalon's configuration
- */
-export async function createImagePlugin(
-  config: ResolvedImageConfig,
-  verbose: boolean
-): Promise<Plugin[]> {
-  if (!config.enabled) {
-    if (verbose) {
-      console.log("   ⏭️  Image optimization disabled");
-    }
-    return [];
-  }
-
-  try {
-    // Dynamic import to avoid hard dependency if user disables images.
-    // Use createRequire from the project root so we resolve the package
-    // from the consuming project's node_modules, not avalon's own context.
-    const require = createRequire(join(process.cwd(), 'package.json'));
-    const { imagetools } = require("vite-imagetools");
-
-    if (verbose) {
-      console.log("   🖼️  Image optimization enabled");
-      console.log(`      Format: ${config.defaultFormat}`);
-      console.log(`      Quality: ${config.quality}`);
-      console.log(`      Widths: ${config.widths.join(", ")}`);
-    }
-
-    const plugin = imagetools({
-      include: config.include,
-      exclude: config.exclude,
-      removeMetadata: config.removeMetadata,
-
-      // Default directives applied to all images unless overridden
-      defaultDirectives: (url) => {
-        const params = new URLSearchParams();
-
-        // Only apply defaults if no format specified
-        if (!url.searchParams.has("format")) {
-          params.set("format", config.defaultFormat);
-        }
-
-        // Only apply quality if not specified
-        if (!url.searchParams.has("quality")) {
-          params.set("quality", String(config.quality));
-        }
-
-        // If ?jsx is used, generate responsive srcset like Qwik
-        if (url.searchParams.has("jsx")) {
-          // Generate widths for srcset if not specified
-          if (!url.searchParams.has("w") && !url.searchParams.has("width")) {
-            params.set("w", config.widths.join(";"));
-          }
-          params.set("as", "picture");
-        }
-
-        return params;
-      },
-    });
-
-    return [plugin as Plugin];
-  } catch (error) {
-    // vite-imagetools not installed
-    const message = error instanceof Error ? error.message : String(error);
-
-    if (message.includes("Cannot find package") || message.includes("MODULE_NOT_FOUND")) {
-      console.warn(
-        "⚠️  Avalon: Image optimization is enabled but vite-imagetools is not installed.\n" +
-        "   Install it with: bun add -d vite-imagetools\n" +
-        "   Or disable image optimization: image: false"
-      );
-      return [];
-    }
-
-    throw error;
-  }
-}
-
-/**
- * Type declarations for image imports
- * Users can reference these in their tsconfig.json
- */
-export const IMAGE_TYPES_DECLARATION = `
-declare module '*.jpg' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.jpeg' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.png' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.webp' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.avif' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.gif' {
-  const src: string;
-  export default src;
-}
-
-declare module '*?jsx' {
-  import type { ComponentType } from 'preact';
-  const Component: ComponentType<{ alt: string; class?: string; style?: Record<string, string> }>;
-  export default Component;
-}
-
-declare module '*&jsx' {
-  import type { ComponentType } from 'preact';
-  const Component: ComponentType<{ alt: string; class?: string; style?: Record<string, string> }>;
-  export default Component;
-}
-`;
+/**
+ * Image Optimization Plugin for Avalon
+ *
+ * Wraps vite-imagetools to provide automatic image optimization with
+ * sensible defaults for responsive images, modern formats, and srcset generation.
+ *
+ * Features:
+ * - Automatic WebP/AVIF conversion
+ * - Responsive srcset generation at multiple breakpoints
+ * - Metadata stripping for privacy
+ * - JSX component output for easy usage in islands
+ *
+ * Usage in components:
+ * ```tsx
+ * // Basic - returns optimized URL
+ * import heroImg from './hero.jpg?w=800&format=webp';
+ *
+ * // With srcset for responsive images
+ * import heroImg from './hero.jpg?w=400;800;1200&format=webp&as=srcset';
+ *
+ * // As JSX component (like Qwik's ?jsx)
+ * import HeroImage from './hero.jpg?w=1200&jsx';
+ * <HeroImage alt="Hero" />
+ * ```
+ */
+
+import type { Plugin } from "vite";
+import type { ResolvedImageConfig } from "./types.ts";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+/**
+ * Creates the vite-imagetools plugin with Avalon's configuration
+ */
+export async function createImagePlugin(
+  config: ResolvedImageConfig,
+  verbose: boolean
+): Promise<Plugin[]> {
+  if (!config.enabled) {
+    if (verbose) {
+      console.log("   ⏭️  Image optimization disabled");
+    }
+    return [];
+  }
+
+  try {
+    // Dynamic import to avoid hard dependency if user disables images.
+    // Use createRequire from the project root so we resolve the package
+    // from the consuming project's node_modules, not avalon's own context.
+    const require = createRequire(join(process.cwd(), 'package.json'));
+    const { imagetools } = require("vite-imagetools");
+
+    if (verbose) {
+      console.log("   🖼️  Image optimization enabled");
+      console.log(`      Format: ${config.defaultFormat}`);
+      console.log(`      Quality: ${config.quality}`);
+      console.log(`      Widths: ${config.widths.join(", ")}`);
+    }
+
+    const plugin = imagetools({
+      include: config.include,
+      exclude: config.exclude,
+      removeMetadata: config.removeMetadata,
+
+      // Default directives applied to all images unless overridden
+      defaultDirectives: (url) => {
+        const params = new URLSearchParams();
+
+        // Only apply defaults if no format specified
+        if (!url.searchParams.has("format")) {
+          params.set("format", config.defaultFormat);
+        }
+
+        // Only apply quality if not specified
+        if (!url.searchParams.has("quality")) {
+          params.set("quality", String(config.quality));
+        }
+
+        // If ?jsx is used, generate responsive srcset like Qwik
+        if (url.searchParams.has("jsx")) {
+          // Generate widths for srcset if not specified
+          if (!url.searchParams.has("w") && !url.searchParams.has("width")) {
+            params.set("w", config.widths.join(";"));
+          }
+          params.set("as", "picture");
+        }
+
+        return params;
+      },
+    });
+
+    return [plugin as Plugin];
+  } catch (error) {
+    // vite-imagetools not installed
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (message.includes("Cannot find package") || message.includes("MODULE_NOT_FOUND")) {
+      console.warn(
+        "⚠️  Avalon: Image optimization is enabled but vite-imagetools is not installed.\n" +
+        "   Install it with: bun add -d vite-imagetools\n" +
+        "   Or disable image optimization: image: false"
+      );
+      return [];
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Type declarations for image imports
+ * Users can reference these in their tsconfig.json
+ */
+export const IMAGE_TYPES_DECLARATION = `
+declare module '*.jpg' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.jpeg' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.png' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.webp' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.avif' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.gif' {
+  const src: string;
+  export default src;
+}
+
+declare module '*?jsx' {
+  import type { ComponentType } from 'preact';
+  const Component: ComponentType<{ alt: string; class?: string; style?: Record<string, string> }>;
+  export default Component;
+}
+
+declare module '*&jsx' {
+  import type { ComponentType } from 'preact';
+  const Component: ComponentType<{ alt: string; class?: string; style?: Record<string, string> }>;
+  export default Component;
+}
+`;