@hypen-space/web 0.2.0 → 0.2.1

package/src/hypen.ts

@@ -0,0 +1,617 @@
+/**
+ * Hypen - High-Level API for Web Applications
+ *
+ * Simple API for rendering Hypen applications (like ReactDOM.render)
+ */
+
+import {
+  BrowserEngine as Engine,
+  HypenModuleInstance,
+  HypenRouter,
+  HypenGlobalContext,
+  componentLoader,
+  Router,
+  Route,
+  Link,
+  type RouterContext,
+  type HypenModuleDefinition,
+} from "@hypen-space/core";
+import { DOMRenderer } from "./dom/renderer.js";
+import type { DebugConfig } from "./dom/debug.js";
+
+export interface HypenConfig {
+  /** Base directory for components (default: "./src/components") */
+  componentsDir?: string;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom WASM path */
+  wasmPath?: string;
+  /** Enable re-render heatmap debugging */
+  debugHeatmap?: boolean;
+  /** Heatmap increment per re-render (default: 5%) */
+  heatmapIncrement?: number;
+  /** Heatmap fade out duration in ms (default: 2000) */
+  heatmapFadeOut?: number;
+}
+
+export class Hypen {
+  private engine: Engine | null = null;
+  private renderer: DOMRenderer | null = null;
+  private moduleInstance: HypenModuleInstance<any> | null = null;
+  private container: HTMLElement | null = null;
+  private config: HypenConfig;
+  private router: HypenRouter;
+  private globalContext: HypenGlobalContext;
+  private moduleInstances = new Map<string, HypenModuleInstance<any>>();
+
+  constructor(config: HypenConfig = {}) {
+    this.config = {
+      componentsDir: "./src/components",
+      debug: false,
+      ...config,
+    };
+
+    // Initialize router and global context
+    this.router = new HypenRouter();
+    this.globalContext = new HypenGlobalContext();
+
+    // Register built-in components
+    componentLoader.register("Router", Router, "");
+    componentLoader.register("Route", Route, "");
+    componentLoader.register("Link", Link, "");
+
+    // Store router and hypen instance in global context for access in components
+    (this.globalContext as any).__router = this.router;
+    (this.globalContext as any).__hypenEngine = this;
+  }
+
+  /**
+   * Initialize the Hypen runtime
+   * Must be called before render()
+   */
+  async init(): Promise<void> {
+    if (this.config.debug) {
+      console.log("[Hypen] Initializing...");
+    }
+
+    // Initialize engine
+    this.engine = new Engine();
+    await this.engine.init(
+      this.config.wasmPath ? { wasmPath: this.config.wasmPath } : undefined
+    );
+
+    if (this.config.debug) {
+      console.log("[Hypen] Engine initialized");
+    }
+  }
+
+  /**
+   * Load all components from the components directory
+   */
+  async loadComponents(componentsDir?: string): Promise<void> {
+    const dir = componentsDir || this.config.componentsDir!;
+
+    if (this.config.debug) {
+      console.log(`[Hypen] Loading components from ${dir}...`);
+    }
+
+    await componentLoader.loadFromComponentsDir(dir);
+
+    if (this.config.debug) {
+      console.log(
+        `[Hypen] Loaded ${componentLoader.getNames().length} components`
+      );
+    }
+  }
+
+  /**
+   * Render a component to a DOM container
+   *
+   * @param componentName - Name of the component to render (e.g., "HomePage")
+   * @param containerSelector - CSS selector or HTMLElement for the mount point
+   */
+  async render(
+    componentName: string,
+    containerSelector: string | HTMLElement
+  ): Promise<void> {
+    if (!this.engine) {
+      throw new Error("[Hypen] Engine not initialized. Call init() first.");
+    }
+
+    // Get the container element
+    if (typeof containerSelector === "string") {
+      const element = document.querySelector(containerSelector);
+      if (!element) {
+        throw new Error(`[Hypen] Container not found: ${containerSelector}`);
+      }
+      this.container = element as HTMLElement;
+    } else {
+      this.container = containerSelector;
+    }
+
+    // Get the component definition
+    const component = componentLoader.get(componentName);
+    if (!component) {
+      throw new Error(
+        `[Hypen] Component "${componentName}" not found. Available: ${componentLoader.getNames().join(", ")}`
+      );
+    }
+
+    if (this.config.debug) {
+      console.log(`[Hypen] Rendering ${componentName} to`, this.container);
+    }
+
+    // Create renderer with debug config
+    this.renderer = new DOMRenderer(this.container, this.engine, {
+      enabled: this.config.debugHeatmap || false,
+      showHeatmap: this.config.debugHeatmap || false,
+      heatmapIncrement: this.config.heatmapIncrement || 5,
+      fadeOutDuration: this.config.heatmapFadeOut || 2000,
+      maxOpacity: 0.8,
+    });
+
+    // Set render callback
+    this.engine.setRenderCallback((patches) => {
+      if (this.config.debug) {
+        console.log(`[Hypen] Applying ${patches.length} patches`);
+      }
+      this.renderer!.applyPatches(patches);
+    });
+
+    // Create router context
+    const routerContext: RouterContext = {
+      root: this.router,
+      current: this.router,
+    };
+
+    // Set context on renderer for component composition
+    this.renderer.setContext(routerContext, this.globalContext);
+
+    // Extract module ID from component name or .id() applicator
+    const moduleId = this.extractModuleId(componentName, component.template);
+
+    // Create module instance with router and global context
+    this.moduleInstance = new HypenModuleInstance(
+      this.engine,
+      component.module,
+      routerContext,
+      this.globalContext
+    );
+
+    // Register module in global context
+    this.globalContext.registerModule(moduleId, this.moduleInstance);
+    this.moduleInstances.set(moduleId, this.moduleInstance);
+
+    // Connect module state changes to renderer
+    this.moduleInstance.onStateChange(() => {
+      const mergedState = this.getMergedState();
+      if (this.config.debug) {
+        console.log(`[Hypen] State changed, merged state:`, mergedState);
+      }
+      this.renderer!.updateState(mergedState);
+    });
+
+    // Set up component resolver for dynamic component composition
+    this.setupComponentResolver();
+
+    // Create module instances for ALL components that have state
+    this.createNestedModuleInstances();
+
+    // Render the UI template
+    this.engine.renderSource(component.template);
+
+    // Update renderer with initial state
+    this.renderer!.updateState(this.getMergedState());
+
+    if (this.config.debug) {
+      console.log(`[Hypen] ${componentName} rendered successfully`);
+    }
+  }
+
+  /**
+   * Unmount and cleanup
+   */
+  async unmount(): Promise<void> {
+    if (this.config.debug) {
+      console.log("[Hypen] Unmounting...");
+    }
+
+    if (this.moduleInstance) {
+      await this.moduleInstance.destroy();
+      this.moduleInstance = null;
+    }
+
+    if (this.container) {
+      this.container.innerHTML = "";
+      this.container = null;
+    }
+
+    this.renderer = null;
+
+    if (this.config.debug) {
+      console.log("[Hypen] Unmounted");
+    }
+  }
+
+  /**
+   * Get the current module instance
+   */
+  getModuleInstance(): HypenModuleInstance<any> | null {
+    return this.moduleInstance;
+  }
+
+  /**
+   * Get the current state
+   */
+  getState(): any {
+    return this.moduleInstance?.getState() ?? null;
+  }
+
+  /**
+   * Get the router instance
+   */
+  getRouter(): HypenRouter {
+    return this.router;
+  }
+
+  /**
+   * Get the global context
+   */
+  getGlobalContext(): HypenGlobalContext {
+    return this.globalContext;
+  }
+
+  /**
+   * Enable or disable debug heatmap mode
+   */
+  setDebugHeatmap(enabled: boolean): void {
+    if (this.renderer) {
+      this.renderer.setDebugConfig({ enabled, showHeatmap: enabled });
+      if (this.config.debug) {
+        console.log(`[Hypen] Debug heatmap ${enabled ? "enabled" : "disabled"}`);
+      }
+    }
+  }
+
+  /**
+   * Reset debug tracking for all elements
+   */
+  resetDebugTracking(): void {
+    if (this.renderer) {
+      this.renderer.resetDebugTracking();
+      if (this.config.debug) {
+        console.log(`[Hypen] Debug tracking reset`);
+      }
+    }
+  }
+
+  /**
+   * Get debug statistics
+   */
+  getDebugStats(): {
+    totalRerenders: number;
+    elementCount: number;
+    avgRerenders: number;
+  } | null {
+    return this.renderer?.getDebugStats() || null;
+  }
+
+  /**
+   * Render a lazy route component into a specific route element
+   * This is called by the Router when a route becomes active
+   */
+  async renderLazyRoute(
+    routePath: string,
+    componentName: string,
+    routeElement: HTMLElement
+  ): Promise<void> {
+    if (!this.engine || !this.renderer) {
+      throw new Error("Engine not initialized");
+    }
+
+    // Get the component from the loader
+    const component = componentLoader.get(componentName);
+    if (!component) {
+      throw new Error(`Component ${componentName} not found`);
+    }
+
+    // Get the component template
+    const template = component.template;
+    if (!template) {
+      throw new Error(`Component ${componentName} has no template`);
+    }
+
+    // Create module instance for this component if it has state
+    if (component.module && !this.moduleInstances.has(componentName)) {
+      const moduleId = this.extractModuleId(componentName, template);
+
+      const routerContext: RouterContext = {
+        root: this.router,
+        current: this.router,
+      };
+
+      const moduleInstance = new HypenModuleInstance(
+        this.engine,
+        component.module,
+        routerContext,
+        this.globalContext
+      );
+
+      this.globalContext.registerModule(moduleId, moduleInstance);
+      this.moduleInstances.set(componentName, moduleInstance);
+
+      // Listen to state changes
+      moduleInstance.onStateChange(() => {
+        const mergedState = this.getMergedState();
+        if (this.config.debug) {
+          console.log(
+            `[Hypen] Lazy component ${componentName} state changed:`,
+            mergedState
+          );
+        }
+        this.renderer!.updateState(mergedState);
+      });
+    }
+
+    // Wait a tick for module instance to initialize and fetch data
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Get the route element's node ID from the renderer
+    const routeNodeId = routeElement.dataset.hypenId;
+    if (!routeNodeId) {
+      throw new Error(`Route element is missing data-hypen-id attribute`);
+    }
+
+    // Get the current merged state
+    const mergedState = this.getMergedState();
+
+    // Render into the Route element
+    this.engine.renderInto(template, routeNodeId, mergedState);
+
+    // Ensure freshly created text nodes are interpolated with current state
+    this.renderer!.updateState(mergedState);
+  }
+
+  /**
+   * Extract module ID from component name or .id() applicator
+   */
+  private extractModuleId(componentName: string, template: string): string {
+    // Look for .id("CustomName") or .id('CustomName') in the template
+    const idMatch = template.match(/\.id\(["']([^"']+)["']\)/);
+    const matchedId = idMatch?.[1];
+    if (matchedId) {
+      return matchedId;
+    }
+
+    // Default to component name
+    return componentName;
+  }
+
+  /**
+   * Create module instances for all components that have state
+   */
+  private createNestedModuleInstances(): void {
+    const routerContext: RouterContext = {
+      root: this.router,
+      current: this.router,
+    };
+
+    // Create built-in Router module instance
+    if (Router && !this.moduleInstances.has("Router")) {
+      const routerInstance = new HypenModuleInstance(
+        this.engine!,
+        Router,
+        routerContext,
+        this.globalContext
+      );
+      this.globalContext.registerModule("Router", routerInstance);
+      this.moduleInstances.set("Router", routerInstance);
+      routerInstance.onStateChange(() => {
+        const mergedState = this.getMergedState();
+        if (this.config.debug) {
+          console.log(`[Hypen] Router state changed:`, mergedState);
+        }
+        this.renderer!.updateState(mergedState);
+      });
+    }
+
+    // Get all registered components
+    const componentNames = componentLoader.getNames();
+
+    for (const name of componentNames) {
+      // Skip if already created
+      if (this.moduleInstances.has(name)) {
+        continue;
+      }
+
+      const comp = componentLoader.get(name);
+      if (!comp || !comp.module) {
+        continue;
+      }
+
+      // Create module instance
+      if (this.config.debug) {
+        console.log(`[Hypen] Creating nested module instance for: ${name}`);
+      }
+
+      const moduleInstance = new HypenModuleInstance(
+        this.engine!,
+        comp.module,
+        routerContext,
+        this.globalContext
+      );
+
+      this.globalContext.registerModule(name, moduleInstance);
+      this.moduleInstances.set(name, moduleInstance);
+
+      // Connect state changes to renderer
+      moduleInstance.onStateChange(() => {
+        const mergedState = this.getMergedState();
+        if (this.config.debug) {
+          console.log(
+            `[Hypen] Nested component ${name} state changed:`,
+            mergedState
+          );
+        }
+        this.renderer!.updateState(mergedState);
+      });
+    }
+  }
+
+  /**
+   * Get merged state from all module instances
+   */
+  private getMergedState(): Record<string, any> {
+    const merged: Record<string, any> = {};
+
+    // Include main module state
+    if (this.moduleInstance) {
+      const mainState = this.moduleInstance.getState();
+      Object.assign(merged, mainState);
+    }
+
+    // Include all nested component states
+    for (const [name, instance] of this.moduleInstances.entries()) {
+      const nestedState = instance.getState();
+      Object.assign(merged, nestedState);
+    }
+
+    return merged;
+  }
+
+  /**
+   * Set up component resolver for the engine
+   */
+  private setupComponentResolver(): void {
+    if (!this.engine) return;
+
+    // List of built-in DOM elements that should NOT be resolved
+    const builtInElements = new Set([
+      "Column",
+      "Row",
+      "Text",
+      "Button",
+      "Image",
+      "Input",
+      "Container",
+      "Box",
+      "Center",
+      "List",
+      "Canvas",
+      "Spacer",
+      "Divider",
+      "ScrollView",
+    ]);
+
+    this.engine.setComponentResolver(
+      (componentName: string, contextPath: string | null) => {
+        // Don't try to resolve built-in DOM elements
+        if (builtInElements.has(componentName)) {
+          return null;
+        }
+
+        if (this.config.debug) {
+          console.log(
+            `[Hypen] Resolving component: ${componentName} (context: ${contextPath})`
+          );
+        }
+
+        // Check if component is registered
+        const componentDef = componentLoader.get(componentName);
+        if (!componentDef) {
+          if (this.config.debug) {
+            console.log(`[Hypen] Component not found: ${componentName}`);
+          }
+          return null;
+        }
+
+        // Router is passthrough, Route is lazy
+        const isPassthrough = componentName === "Router";
+        const isLazy = componentName === "Route";
+
+        const resolved = {
+          source: componentDef.template,
+          path: componentDef.path || componentName,
+          passthrough: isPassthrough,
+          lazy: isLazy,
+        };
+
+        if (this.config.debug) {
+          const flags = [];
+          if (isPassthrough) flags.push("passthrough");
+          if (isLazy) flags.push("lazy");
+          const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+          console.log(
+            `[Hypen] Resolved ${componentName} -> ${resolved.path}${flagStr}`
+          );
+        }
+
+        return resolved;
+      }
+    );
+  }
+}
+
+/**
+ * Quick render function (like ReactDOM.render)
+ *
+ * @example
+ * ```typescript
+ * import { render } from "@hypen-space/web";
+ *
+ * await render("HomePage", "#app");
+ * ```
+ */
+export async function render(
+  componentName: string,
+  containerSelector: string | HTMLElement,
+  config?: HypenConfig
+): Promise<Hypen> {
+  const hypen = new Hypen(config);
+  await hypen.init();
+  await hypen.loadComponents();
+  await hypen.render(componentName, containerSelector);
+  return hypen;
+}
+
+/**
+ * Render with explicit component loading
+ *
+ * @example
+ * ```typescript
+ * import { renderWithComponents } from "@hypen-space/web";
+ * import HomePage from "./components/HomePage/component";
+ * import homePageTemplate from "./components/HomePage/component.hypen";
+ *
+ * await renderWithComponents(
+ *   { HomePage: { module: HomePage, template: homePageTemplate } },
+ *   "HomePage",
+ *   "#app"
+ * );
+ * ```
+ */
+export async function renderWithComponents(
+  components: Record<string, { module: HypenModuleDefinition; template: string }>,
+  componentName: string,
+  containerSelector: string | HTMLElement,
+  config?: HypenConfig
+): Promise<Hypen> {
+  const hypen = new Hypen(config);
+  await hypen.init();
+
+  // Register components manually
+  for (const [name, { module, template }] of Object.entries(components)) {
+    let processedTemplate = template;
+
+    // If template starts with "module ComponentName {", extract just the children
+    const moduleMatch = template.match(/^\s*module\s+\w+\s*\{([\s\S]*)\}\s*$/);
+    if (moduleMatch && moduleMatch[1]) {
+      processedTemplate = moduleMatch[1].trim();
+    }
+
+    componentLoader.register(name, module, processedTemplate);
+  }
+
+  await hypen.render(componentName, containerSelector);
+  return hypen;
+}

package/src/index.ts

@@ -45,6 +45,13 @@ export { RerenderTracker, type DebugConfig, defaultDebugConfig } from "./dom/deb
 export { CanvasRenderer } from "./canvas/renderer.js";
 export { canvasHandler, canvasApplicators } from "./dom/canvas/index.js";
 
+// ============================================================================
+// HIGH-LEVEL API
+// ============================================================================
+
+export { Hypen, render, renderWithComponents } from "./hypen.js";
+export type { HypenConfig } from "./hypen.js";
+
 // Re-export core types that web users commonly need
 export type {
   Patch,
@@ -53,4 +60,4 @@ export type {
   RouterContext,
   HypenModuleInstance,
   HypenGlobalContext,
-} from "@hypen/core";
+} from "@hypen-space/core";