@useavalon/avalon 0.1.12 → 0.1.13

package/src/vite-plugin/config.ts

@@ -0,0 +1,266 @@
+/**
+ * Configuration Resolution for Avalon Vite Plugin
+ *
+ * This module provides default configuration values and the resolution
+ * function that merges user configuration with defaults.
+ */
+
+import type {
+  AvalonPluginConfig,
+  ResolvedAvalonConfig,
+  ResolvedMDXConfig,
+  ResolvedModulesConfig,
+  ResolvedImageConfig,
+  ModulesConfig,
+  ImageConfig,
+} from "./types.ts";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import process from "node:process";
+
+/**
+ * Default MDX configuration values
+ */
+export const DEFAULT_MDX_CONFIG: ResolvedMDXConfig = {
+  jsxImportSource: "preact",
+  syntaxHighlighting: true,
+  remarkPlugins: [],
+  rehypePlugins: [],
+};
+
+/**
+ * Default image optimization configuration values
+ */
+export const DEFAULT_IMAGE_CONFIG: ResolvedImageConfig = {
+  enabled: true,
+  defaultFormat: "webp",
+  quality: 80,
+  widths: [200, 400, 600, 800, 1200],
+  removeMetadata: true,
+  include: /^[^?]+\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\?.*)?$/,
+  exclude: "public/**/*",
+};
+
+/**
+ * Default configuration values for the Avalon plugin
+ * These are used when the user doesn't provide specific values
+ */
+export const DEFAULT_CONFIG: Omit<ResolvedAvalonConfig, "isDev"> = {
+  pagesDir: "src/pages",
+  layoutsDir: "src/layouts",
+  modules: null,
+  integrations: [],
+  mdx: DEFAULT_MDX_CONFIG,
+  image: DEFAULT_IMAGE_CONFIG,
+  verbose: false,
+  autoDiscoverIntegrations: true,
+  validateIntegrations: true,
+  showWarnings: true,
+  lazyIntegrations: true,
+};
+
+/**
+ * Default modules configuration values
+ */
+export const DEFAULT_MODULES_CONFIG = {
+  pagesDirName: "pages",
+  layoutsDirName: "layouts",
+};
+
+/**
+ * Resolves the modules configuration
+ */
+function resolveModulesConfig(
+  modules: string | ModulesConfig | undefined
+): ResolvedModulesConfig | null {
+  if (!modules) return null;
+
+  if (typeof modules === "string") {
+    return {
+      dir: modules,
+      pagesDirName: DEFAULT_MODULES_CONFIG.pagesDirName,
+      layoutsDirName: DEFAULT_MODULES_CONFIG.layoutsDirName,
+    };
+  }
+
+  return {
+    dir: modules.dir,
+    pagesDirName: modules.pagesDirName ?? DEFAULT_MODULES_CONFIG.pagesDirName,
+    layoutsDirName: modules.layoutsDirName ?? DEFAULT_MODULES_CONFIG.layoutsDirName,
+  };
+}
+
+/**
+ * Resolves the image optimization configuration
+ */
+function resolveImageConfig(
+  image: boolean | ImageConfig | undefined
+): ResolvedImageConfig {
+  // Explicitly disabled
+  if (image === false) {
+    return { ...DEFAULT_IMAGE_CONFIG, enabled: false };
+  }
+
+  // Default or explicitly enabled with no options
+  if (image === undefined || image === true) {
+    return DEFAULT_IMAGE_CONFIG;
+  }
+
+  // Custom config object
+  return {
+    enabled: image.enabled ?? DEFAULT_IMAGE_CONFIG.enabled,
+    defaultFormat: image.defaultFormat ?? DEFAULT_IMAGE_CONFIG.defaultFormat,
+    quality: image.quality ?? DEFAULT_IMAGE_CONFIG.quality,
+    widths: image.widths ?? DEFAULT_IMAGE_CONFIG.widths,
+    removeMetadata: image.removeMetadata ?? DEFAULT_IMAGE_CONFIG.removeMetadata,
+    include: image.include ?? DEFAULT_IMAGE_CONFIG.include,
+    exclude: image.exclude ?? DEFAULT_IMAGE_CONFIG.exclude,
+  };
+}
+
+/**
+ * Resolves user configuration by merging with defaults
+ *
+ * @param userConfig - Partial configuration provided by the user
+ * @param isDev - Whether the application is running in development mode
+ * @returns Fully resolved configuration with all defaults applied
+ *
+ * @example
+ * ```ts
+ * const resolved = resolveConfig({ integrations: ["react"] }, true);
+ * // resolved.pagesDir === "src/pages" (default)
+ * // resolved.integrations === ["react"] (user provided)
+ * // resolved.isDev === true
+ * ```
+ */
+export function resolveConfig(
+  userConfig: AvalonPluginConfig | undefined,
+  isDev: boolean
+): ResolvedAvalonConfig {
+  const config = userConfig ?? {};
+  const modules = resolveModulesConfig(config.modules);
+  const image = resolveImageConfig(config.image);
+
+  return {
+    pagesDir: config.pagesDir ?? DEFAULT_CONFIG.pagesDir,
+    layoutsDir: config.layoutsDir ?? DEFAULT_CONFIG.layoutsDir,
+    modules,
+    integrations: config.integrations ?? DEFAULT_CONFIG.integrations,
+    mdx: {
+      jsxImportSource:
+        config.mdx?.jsxImportSource ?? DEFAULT_MDX_CONFIG.jsxImportSource,
+      syntaxHighlighting:
+        config.mdx?.syntaxHighlighting ?? DEFAULT_MDX_CONFIG.syntaxHighlighting,
+      remarkPlugins:
+        config.mdx?.remarkPlugins ?? DEFAULT_MDX_CONFIG.remarkPlugins,
+      rehypePlugins:
+        config.mdx?.rehypePlugins ?? DEFAULT_MDX_CONFIG.rehypePlugins,
+    },
+    image,
+    verbose: config.verbose ?? DEFAULT_CONFIG.verbose,
+    autoDiscoverIntegrations:
+      config.autoDiscoverIntegrations ?? DEFAULT_CONFIG.autoDiscoverIntegrations,
+    validateIntegrations:
+      config.validateIntegrations ?? DEFAULT_CONFIG.validateIntegrations,
+    showWarnings: config.showWarnings ?? DEFAULT_CONFIG.showWarnings,
+    lazyIntegrations: config.lazyIntegrations ?? DEFAULT_CONFIG.lazyIntegrations,
+    isDev,
+  };
+}
+
+
+/**
+ * Result of directory existence check
+ */
+export interface DirectoryCheckResult {
+  /** The directory path that was checked */
+  path: string;
+  /** The resolved absolute path */
+  absolutePath: string;
+  /** Whether the directory exists */
+  exists: boolean;
+  /** The type of directory (pages, layouts) */
+  type: "pages" | "layouts";
+}
+
+/**
+ * Check if configured directories exist and log warnings for missing ones
+ *
+ * This function checks if the configured directories (pagesDir, layoutsDir)
+ * exist on the filesystem. If a directory doesn't exist, it logs a warning but
+ * does NOT throw an error, allowing the application to continue.
+ *
+ * @param config - The resolved Avalon configuration
+ * @param projectRoot - The root directory of the project (defaults to process.cwd())
+ * @returns Array of directory check results
+ *
+ * @example
+ * ```ts
+ * const results = checkDirectoriesExist(resolvedConfig, '/path/to/project');
+ * // Logs warnings for any missing directories
+ * // Returns results for programmatic access
+ * ```
+ */
+export function checkDirectoriesExist(
+  config: ResolvedAvalonConfig,
+  projectRoot: string = process.cwd()
+): DirectoryCheckResult[] {
+  const directories: Array<{ path: string; type: DirectoryCheckResult["type"] }> = [];
+  
+  // Only check pagesDir if modules is not configured (traditional architecture)
+  // When using modular architecture, pages are discovered from modules
+  if (!config.modules && config.pagesDir) {
+    directories.push({ path: config.pagesDir, type: "pages" });
+  }
+  
+  // Always check layoutsDir if it's set
+  if (config.layoutsDir) {
+    directories.push({ path: config.layoutsDir, type: "layouts" });
+  }
+
+  const results: DirectoryCheckResult[] = [];
+
+  for (const { path, type } of directories) {
+    const absolutePath = resolve(projectRoot, path);
+    const exists = existsSync(absolutePath);
+
+    results.push({
+      path,
+      absolutePath,
+      exists,
+      type,
+    });
+
+    if (!exists && config.showWarnings) {
+      console.warn(
+        `⚠️  Avalon: ${type} directory '${path}' does not exist (resolved to: ${absolutePath}). ` +
+        `This directory will be skipped.`
+      );
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Log a summary of directory check results
+ *
+ * @param results - The directory check results
+ * @param verbose - Whether to log verbose output
+ */
+export function logDirectoryCheckSummary(
+  results: DirectoryCheckResult[],
+  verbose: boolean
+): void {
+  const missing = results.filter((r) => !r.exists);
+  const existing = results.filter((r) => r.exists);
+
+  if (verbose) {
+    if (existing.length > 0) {
+      console.log(`   ✅ Found directories: ${existing.map((r) => r.path).join(", ")}`);
+    }
+    if (missing.length > 0) {
+      console.log(`   ⚠️  Missing directories: ${missing.map((r) => r.path).join(", ")}`);
+    }
+  }
+}

package/src/vite-plugin/errors.ts

@@ -0,0 +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);
+}

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

@@ -0,0 +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;
+}
+`;

package/src/vite-plugin/integration-activator.ts

@@ -0,0 +1,126 @@
+/**
+ * Integration Activator for Avalon Vite Plugin
+ *
+ * This module handles the activation of framework integrations based on
+ * the plugin configuration. It validates integration names and loads
+ * the appropriate integration packages.
+ */
+
+import type { IntegrationName, ResolvedAvalonConfig } from "./types.ts";
+import { loadIntegration } from "../islands/integration-loader.ts";
+import { IntegrationError } from "./errors.ts";
+
+/**
+ * Valid integration names that can be activated
+ * This array is used for validation and error messages
+ */
+export const VALID_INTEGRATION_NAMES: readonly IntegrationName[] = [
+  "react",
+  "preact",
+  "vue",
+  "svelte",
+  "solid",
+  "lit",
+  "qwik",
+] as const;
+
+/**
+ * Check if a string is a valid integration name
+ *
+ * @param name - The name to validate
+ * @returns True if the name is a valid IntegrationName
+ */
+export function isValidIntegrationName(name: string): name is IntegrationName {
+  return VALID_INTEGRATION_NAMES.includes(name as IntegrationName);
+}
+
+/**
+ * Activates the specified integrations
+ *
+ * Uses the existing integration loader and registry to load and activate
+ * framework integrations based on the configuration.
+ *
+ * @param config - The resolved Avalon configuration
+ * @param activeIntegrations - Set to track which integrations have been activated
+ * @throws IntegrationError if an invalid integration name is provided or loading fails
+ *
+ * @example
+ * ```ts
+ * const activeIntegrations = new Set<IntegrationName>();
+ * await activateIntegrations(resolvedConfig, activeIntegrations);
+ * // activeIntegrations now contains all successfully loaded integrations
+ * ```
+ */
+export async function activateIntegrations(
+  config: ResolvedAvalonConfig,
+  activeIntegrations: Set<IntegrationName>
+): Promise<void> {
+  const { integrations } = config;
+
+  // Load explicitly specified integrations
+  for (const name of integrations) {
+    // Validate integration name
+    if (!isValidIntegrationName(name)) {
+      throw new IntegrationError(
+        `Invalid integration name '${name}'. Valid integration names are: ${VALID_INTEGRATION_NAMES.join(", ")}`,
+        name
+      );
+    }
+
+    // Skip if already activated
+    if (activeIntegrations.has(name)) {
+      continue;
+    }
+
+    try {
+      await loadIntegration(name);
+      activeIntegrations.add(name);
+    } catch (error) {
+      throw new IntegrationError(
+        `Failed to activate integration. Is @useavalon/${name} installed?`,
+        name,
+        error as Error
+      );
+    }
+  }
+}
+
+/**
+ * Activate a single integration by name
+ *
+ * @param name - The integration name to activate
+ * @param activeIntegrations - Set to track which integrations have been activated
+ * @param verbose - Whether to log activation messages
+ * @returns True if the integration was activated, false if already active
+ * @throws IntegrationError if the name is invalid or loading fails
+ */
+export async function activateSingleIntegration(
+  name: string,
+  activeIntegrations: Set<IntegrationName>,
+  _verbose: boolean = false
+): Promise<boolean> {
+  // Validate integration name
+  if (!isValidIntegrationName(name)) {
+    throw new IntegrationError(
+      `Invalid integration name '${name}'. Valid integration names are: ${VALID_INTEGRATION_NAMES.join(", ")}`,
+      name
+    );
+  }
+
+  // Skip if already activated
+  if (activeIntegrations.has(name)) {
+    return false;
+  }
+
+  try {
+    await loadIntegration(name);
+    activeIntegrations.add(name);
+    return true;
+  } catch (error) {
+    throw new IntegrationError(
+      `Failed to activate integration. Is @useavalon/${name} installed?`,
+      name,
+      error as Error
+    );
+  }
+}