@useavalon/avalon 0.1.13 → 0.1.14

package/src/vite-plugin/config.ts

@@ -1,266 +0,0 @@
-/**
- * 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

@@ -1,127 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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

@@ -1,126 +0,0 @@
-/**
- * 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
-    );
-  }
-}