@stacksjs/stx/dist/hydration.d.ts

A performant UI Framework. Powered by Bun.

/**
 * Serialize state for client hydration
 * Called during server-side rendering
 */
export declare function serializeState(state: Partial<HydrationState>): string;
/**
 * Generate the state injection script for server-rendered HTML
 */
export declare function generateStateScript(state: Partial<HydrationState>): string;
/**
 * Generate event bindings data attribute
 */
export declare function generateEventBindings(events: EventBinding[]): string;
/**
 * Extract and parse state from server-rendered HTML
 */
export declare function extractState(): HydrationState | null;
/**
 * Generate the hydration runtime script for embedding in HTML
 */
export declare function generateHydrationScript(state?: Partial<HydrationState>): string;
/**
 * Get or create the hydration runtime
 */
export declare function getHydrationRuntime(options?: HydrationOptions): HydrationRuntime;
/**
 * Start hydration (convenience function)
 */
export declare function hydrate(options?: HydrationOptions): Promise<void>;
/**
 * Generate hydration CSS
 */
export declare function generateHydrationCSS(): string;
/**
 * STX Hydration Runtime
 *
 * Comprehensive client-side hydration system that bridges server-rendered
 * HTML with client-side interactivity. Similar to React's hydrateRoot or
 * Vue's createSSRApp.
 *
 * ## Features
 *
 * - Full page hydration with state restoration
 * - Selective/partial hydration (islands architecture)
 * - Event handler binding from server-rendered HTML
 * - Integration with stx reactivity system
 * - Seamless SPA router integration
 * - Progressive enhancement support
 * - Error boundaries for hydration failures
 *
 * ## Usage
 *
 * Server-side (stx template):
 * ```html
 * <script>
 * const count = 0
 * const user = { name: 'Alice' }
 * </script>
 *
 * <button @click="count++">Count: {{ count }}</button>
 * <p>Hello, {{ user.name }}</p>
 * ```
 *
 * The framework automatically:
 * 1. Renders HTML on server
 * 2. Serializes state and embeds in HTML
 * 3. Client loads, hydrates, binds events
 * 4. Page becomes interactive
 *
 * @module hydration
 */
// =============================================================================
// Types
// =============================================================================
export declare interface HydrationState {
  refs: Record<string, unknown>
  reactive: Record<string, unknown>
  props: Record<string, unknown>
  routeParams: Record<string, string>
  stores: Record<string, unknown>
  meta: {
    title?: string
    description?: string
    url?: string
  }
  timestamp: number
  checksum?: string
}
export declare interface HydrationOptions {
  root?: string | HTMLElement
  strict?: boolean
  onHydrating?: () => void
  onHydrated?: () => void
  onError?: (error: Error) => void
  performance?: boolean
  timeout?: number
}
export declare interface EventBinding {
  type: string
  handler: string
  modifiers?: string[]
  preventDefault?: boolean
  stopPropagation?: boolean
}
export declare interface ComponentHydrationConfig {
  id: string
  name: string
  strategy: 'eager' | 'lazy' | 'idle' | 'visible' | 'interaction'
  props: Record<string, unknown>
  events: EventBinding[]
}
/**
 * Main hydration class
 */
export declare class HydrationRuntime {
  private state: HydrationState | null;
  private options: Required<HydrationOptions>;
  private root: HTMLElement | null;
  private isHydrated: any;
  private pendingComponents: Map<string, ComponentHydrationConfig>;
  private hydratedComponents: Set<string>;
  constructor(options?: HydrationOptions);
  hydrate(): Promise<void>;
  private runHydration(): Promise<void>;
  private restoreGlobalState(): void;
  private hydrateComponents(): Promise<void>;
  private hydrateComponent(el: HTMLElement, config: ComponentHydrationConfig): Promise<void>;
  private restoreComponentState(el: HTMLElement, state: unknown): void;
  private setupVisibleHydration(el: HTMLElement, config: ComponentHydrationConfig): void;
  private setupIdleHydration(el: HTMLElement, config: ComponentHydrationConfig): void;
  private setupInteractionHydration(el: HTMLElement, config: ComponentHydrationConfig): void;
  private bindEventHandlers(): void;
  private bindElementEvents(el: HTMLElement): void;
  private bindDirectiveEvents(): void;
  private parseModifiers(el: HTMLElement, eventType: string): string[];
  private bindSingleEvent(el: HTMLElement, event: EventBinding): void;
  private resolveHandler(handlerStr: string): ((e: Event) => void) | null;
  private bindComponentEvents(el: HTMLElement): void;
  private initializeComponentReactivity(el: HTMLElement, config: ComponentHydrationConfig): void;
  private initializeReactiveBindings(): void;
  private getTextNodesWithExpressions(root: HTMLElement): Array<{
    node: Text
    expressions: string[]
  }>;
  private setupTextNodeBinding(node: Text, expression: string): void;
  private setupAttributeBinding(el: HTMLElement, attr: string, expression: string): void;
  private setupReactiveBinding(el: HTMLElement, expression: string): void;
  private setupRouterIntegration(): void;
  getState(): HydrationState | null;
  hydrateById(componentId: string): Promise<void>;
}
export default {
  HydrationRuntime,
  serializeState,
  generateStateScript,
  generateHydrationScript,
  generateHydrationCSS,
  extractState,
  getHydrationRuntime,
  hydrate,
};