@useavalon/avalon 0.1.11 → 0.1.12

package/src/client/adapters/solid-adapter.ts

@@ -1,451 +0,0 @@
-/**
- * Solid HMR Adapter
- * 
- * Provides Hot Module Replacement support for Solid components using Solid Refresh.
- * Integrates with vite-plugin-solid to preserve signal subscriptions and reactive computations.
- * Handles Solid's fine-grained reactivity system during hot updates.
- * 
- * Requirements: 2.5
- */
-
-/// <reference lib="dom" />
-
-import { BaseFrameworkAdapter, type StateSnapshot } from '../framework-adapter.ts';
-
-/**
- * Solid component type
- * Solid components are functions that return JSX
- */
-type SolidComponent<P = Record<string, unknown>> = (props: P) => unknown;
-
-/**
- * Solid Web module interface
- */
-interface SolidWebModule {
-  hydrate(
-    fn: () => unknown,
-    node: HTMLElement,
-    options?: { renderId?: string }
-  ): () => void;
-  render(
-    fn: () => unknown,
-    node: HTMLElement
-  ): () => void;
-  createComponent<P>(
-    component: SolidComponent<P>,
-    props: P
-  ): unknown;
-}
-
-/**
- * Solid HMR Runtime interface
- * Provided by vite-plugin-solid for hot module replacement
- */
-interface SolidHMRRuntime {
-  /**
-   * Create a record for a component
-   */
-  createRecord(id: string, component: SolidComponent): void;
-  
-  /**
-   * Reload a component
-   */
-  reload(id: string, component: SolidComponent): void;
-  
-  /**
-   * Update component
-   */
-  update(id: string, component: SolidComponent): void;
-}
-
-/**
- * Global Solid HMR runtime
- * Injected by vite-plugin-solid
- */
-declare global {
-  var __SOLID_HMR__: SolidHMRRuntime | undefined;
-}
-
-/**
- * Solid-specific state snapshot
- * Extends base snapshot with Solid-specific state like signal values
- */
-interface SolidStateSnapshot extends StateSnapshot {
-  framework: 'solid';
-  data: {
-    /**
-     * Signal values captured from component
-     * Note: Solid's fine-grained reactivity makes this challenging
-     */
-    signalValues?: Record<string, unknown>;
-    
-    /**
-     * Component display name for debugging
-     */
-    componentName?: string;
-    
-    /**
-     * Props at time of state capture
-     */
-    capturedProps?: Record<string, unknown>;
-    
-    /**
-     * Render ID for hydration
-     */
-    renderId?: string;
-  };
-}
-
-/**
- * Solid HMR Adapter
- * 
- * Leverages Solid Refresh (provided by vite-plugin-solid) to:
- * - Preserve signal subscriptions across updates
- * - Maintain reactive computations
- * - Handle component updates without full remount
- * 
- * Solid Refresh works through the __SOLID_HMR__ API:
- * 1. When a component module is updated, Vite sends an HMR event
- * 2. We use __SOLID_HMR__.reload() to hot-reload the component
- * 3. Solid Refresh preserves signal subscriptions automatically
- * 4. Reactive computations are maintained across updates
- * 5. The component re-renders with preserved reactive state
- */
-export class SolidHMRAdapter extends BaseFrameworkAdapter {
-  readonly name = 'solid';
-  
-  /**
-   * Store Solid dispose functions for each island to enable proper cleanup
-   */
-  private disposers: WeakMap<HTMLElement, () => void> = new WeakMap();
-  
-  /**
-   * Store component IDs for HMR runtime
-   */
-  private componentIds: WeakMap<HTMLElement, string> = new WeakMap();
-
-  /**
-   * Check if a component is a Solid component
-   * 
-   * Solid components are:
-   * - Functions that return JSX
-   * - May use createSignal, createEffect, etc.
-   * - Typically have .solid.tsx extension (but not always)
-   */
-  canHandle(component: unknown): boolean {
-    if (!component) return false;
-    
-    // Check if it's a function (Solid components are functions)
-    if (typeof component === 'function') {
-      const comp = component as unknown as Record<string, unknown>;
-      
-      // Check for Solid-specific markers
-      // Solid components may have __solid marker from vite-plugin-solid
-      if (comp.__solid) {
-        return true;
-      }
-      
-      // Check function signature - Solid components typically accept props
-      // and return JSX (which is compiled to function calls)
-      try {
-        const funcStr = component.toString();
-        
-        // Look for Solid-specific patterns
-        // - createSignal, createEffect, createMemo, etc.
-        // - JSX patterns (though this is less reliable after compilation)
-        if (
-          funcStr.includes('createSignal') ||
-          funcStr.includes('createEffect') ||
-          funcStr.includes('createMemo') ||
-          funcStr.includes('createResource') ||
-          funcStr.includes('createStore') ||
-          funcStr.includes('_$') || // Solid's compiled JSX helper prefix
-          funcStr.includes('_tmpl$') // Solid's template marker
-        ) {
-          return true;
-        }
-      } catch {
-        // Ignore errors from toString()
-      }
-      
-      // If we can't determine definitively, assume it could be a Solid component
-      // if it's a function (Solid components are just functions)
-      // This is a fallback - we'll let Solid's hydration handle validation
-      return true;
-    }
-    
-    // Check if it's a Solid component object (wrapped or exported)
-    if (typeof component !== 'object') {
-      return false;
-    }
-
-    const obj = component as Record<string, unknown>;
-    
-    // Check for default export pattern
-    if (obj.default && typeof obj.default === 'function') {
-      return this.canHandle(obj.default);
-    }
-    
-    // Check for Solid component markers
-    if (obj.__solid) {
-      return true;
-    }
-    
-    return false;
-  }
-
-  /**
-   * Preserve Solid component state before HMR update
-   * 
-   * Solid Refresh handles most state preservation automatically through
-   * its fine-grained reactivity system. We capture additional DOM state
-   * and props for fallback.
-   * 
-   * Note: Solid's signals are not easily accessible from outside the component,
-   * so we rely on Solid Refresh to preserve them.
-   */
-  override preserveState(island: HTMLElement): SolidStateSnapshot | null {
-    try {
-      // Get base DOM state
-      const baseSnapshot = super.preserveState(island);
-      if (!baseSnapshot) return null;
-
-      // Get Solid-specific data
-      const propsAttr = island.getAttribute('data-props');
-      const capturedProps = propsAttr ? JSON.parse(propsAttr) : {};
-      
-      // Try to get component name from the island
-      const src = island.getAttribute('data-src') || '';
-      const componentName = this.extractComponentName(src);
-      
-      // Get render ID for hydration
-      const renderId = island.dataset.solidRenderId || island.dataset.renderId;
-
-      const solidSnapshot: SolidStateSnapshot = {
-        ...baseSnapshot,
-        framework: 'solid',
-        data: {
-          componentName,
-          capturedProps,
-          renderId,
-        },
-      };
-
-      return solidSnapshot;
-    } catch (error) {
-      console.warn('Failed to preserve Solid state:', error);
-      return null;
-    }
-  }
-
-  /**
-   * Update Solid component with HMR
-   * 
-   * This method integrates with Solid Refresh:
-   * 1. Solid Refresh is automatically enabled by vite-plugin-solid
-   * 2. When a module updates, Vite sends an HMR event
-   * 3. We use __SOLID_HMR__ to reload the component
-   * 4. Solid Refresh preserves signal subscriptions automatically
-   * 5. Reactive computations are maintained
-   * 6. The component re-renders with preserved reactive state
-   */
-  async update(
-    island: HTMLElement,
-    newComponent: unknown,
-    props: Record<string, unknown>
-  ): Promise<void> {
-    if (!this.canHandle(newComponent)) {
-      throw new Error('Component is not a valid Solid component');
-    }
-
-    // Extract the actual component function
-    let Component: SolidComponent;
-    if (typeof newComponent === 'object' && newComponent !== null) {
-      const obj = newComponent as Record<string, unknown>;
-      if (obj.default && typeof obj.default === 'function') {
-        Component = obj.default as SolidComponent;
-      } else {
-        throw new Error('Solid component object must have a default export');
-      }
-    } else if (typeof newComponent === 'function') {
-      Component = newComponent as SolidComponent;
-    } else {
-      throw new Error('Invalid Solid component type');
-    }
-
-    try {
-      // Check if we have an existing disposer
-      const existingDisposer = this.disposers.get(island);
-      const componentId = this.componentIds.get(island);
-
-      // Try to use Solid HMR runtime if available
-      const hmrRuntime = globalThis.__SOLID_HMR__;
-      
-      if (hmrRuntime && componentId) {
-        // Use Solid's HMR runtime for hot reload
-        // This preserves signal subscriptions and reactive computations automatically
-        try {
-          hmrRuntime.reload(componentId, Component);
-          
-          // If we have an existing component, Solid Refresh handles the update
-          // We don't need to do anything else
-          if (existingDisposer) {
-            return;
-          }
-        } catch (error) {
-          console.warn('Solid HMR runtime reload failed, falling back to full remount:', error);
-        }
-      }
-
-      // Clean up existing component if present
-      if (existingDisposer) {
-        try {
-          existingDisposer();
-          this.disposers.delete(island);
-        } catch (error) {
-          console.warn('Failed to dispose existing Solid component:', error);
-        }
-      }
-
-      // Dynamically import Solid at runtime
-      // This is resolved by Vite in the browser
-      const solidWebModule = await import('solid-js/web') as SolidWebModule;
-      const { hydrate, createComponent } = solidWebModule;
-
-      // Get render ID for hydration
-      const renderId = island.dataset.solidRenderId || island.dataset.renderId;
-      
-      // Check if we have SSR content to hydrate
-
-      // Hydrate or render the component
-      const dispose = hydrate(
-        () => createComponent(Component, props),
-        island,
-        {
-          renderId,
-        }
-      );
-      
-      // Store disposer for future updates
-      this.disposers.set(island, dispose);
-      
-      // Generate component ID for HMR runtime
-      const src = island.getAttribute('data-src') || '';
-      const newComponentId = this.generateComponentId(src);
-      this.componentIds.set(island, newComponentId);
-      
-      // Register with HMR runtime if available
-      if (hmrRuntime) {
-        try {
-          hmrRuntime.createRecord(newComponentId, Component);
-        } catch (error) {
-          console.warn('Failed to register with Solid HMR runtime:', error);
-        }
-      }
-
-      // Mark as hydrated
-      island.setAttribute('data-hydrated', 'true');
-      island.setAttribute('data-hydration-status', 'success');
-      
-    } catch (error) {
-      console.error('Solid HMR update failed:', error);
-      island.setAttribute('data-hydration-status', 'error');
-      throw error;
-    }
-  }
-
-  /**
-   * Restore Solid component state after HMR update
-   * 
-   * Solid Refresh handles most state restoration automatically through
-   * its fine-grained reactivity system. We restore DOM state (scroll, focus,
-   * form values) as a supplement.
-   */
-  override restoreState(island: HTMLElement, state: StateSnapshot): void {
-    try {
-      // Restore DOM state (scroll, focus, form values)
-      super.restoreState(island, state);
-      
-      // Solid Refresh handles signal subscriptions and reactive computations
-      // automatically, so we don't need to do anything special here
-      
-    } catch (error) {
-      console.warn('Failed to restore Solid state:', error);
-    }
-  }
-
-  /**
-   * Handle errors during Solid HMR update
-   * 
-   * Provides Solid-specific error handling with helpful messages
-   */
-  override handleError(island: HTMLElement, error: Error): void {
-    console.error('Solid HMR error:', error);
-    
-    // Use base error handling
-    super.handleError(island, error);
-    
-    // Add Solid-specific error information
-    const errorIndicator = island.querySelector('.hmr-error-indicator');
-    if (errorIndicator) {
-      const errorMessage = error.message;
-      
-      // Provide helpful hints for common Solid errors
-      let hint = '';
-      if (errorMessage.includes('signal') || errorMessage.includes('Signal')) {
-        hint = ' (Hint: Check signal usage - signals must be called as functions)';
-      } else if (errorMessage.includes('effect') || errorMessage.includes('Effect')) {
-        hint = ' (Hint: Check effect usage - effects run after render)';
-      } else if (errorMessage.includes('hydration') || errorMessage.includes('hydrate')) {
-        hint = ' (Hint: Server and client render must match)';
-      } else if (errorMessage.includes('createSignal') || errorMessage.includes('createEffect')) {
-        hint = ' (Hint: Solid primitives must be called inside component functions)';
-      } else if (errorMessage.includes('reactive')) {
-        hint = ' (Hint: Check reactive dependencies - they must be accessed inside tracking scopes)';
-      }
-      
-      errorIndicator.textContent = `Solid HMR Error: ${errorMessage}${hint}`;
-    }
-  }
-
-  /**
-   * Extract component name from source path
-   * Used for debugging and error messages
-   */
-  private extractComponentName(src: string): string {
-    const parts = src.split('/');
-    const filename = parts[parts.length - 1];
-    return filename.replace(/\.solid\.(tsx?|jsx?)$/, '').replace(/\.(tsx?|jsx?)$/, '');
-  }
-
-  /**
-   * Generate a unique component ID for HMR runtime
-   */
-  private generateComponentId(src: string): string {
-    // Use the source path as the component ID
-    // This ensures consistency across HMR updates
-    return src.replace(/[^a-zA-Z0-9]/g, '_');
-  }
-
-  /**
-   * Clean up Solid component when island is removed
-   * This should be called when an island is unmounted
-   */
-  unmount(island: HTMLElement): void {
-    const disposer = this.disposers.get(island);
-    if (disposer) {
-      try {
-        disposer();
-        this.disposers.delete(island);
-        this.componentIds.delete(island);
-      } catch (error) {
-        console.warn('Failed to unmount Solid component:', error);
-      }
-    }
-  }
-}
-
-/**
- * Create and export a singleton instance of the Solid HMR adapter
- */
-export const solidAdapter = new SolidHMRAdapter();