@hypen-space/web 0.2.11 → 0.3.0

package/src/dom/components/hypenapp.ts

@@ -0,0 +1,348 @@
+/**
+ * HypenApp Component
+ *
+ * Embeds a remote Hypen app via WebSocket
+ *
+ * Usage in Hypen DSL:
+ * ```hypen
+ * HypenApp("ws://localhost:3000")
+ *
+ * // Or with named prop:
+ * HypenApp(url: "ws://localhost:3000")
+ * ```
+ */
+
+import type { ComponentHandler } from "./index.js";
+import { RemoteEngine } from "@hypen-space/core/remote/client";
+import type { Patch } from "@hypen-space/core/remote";
+
+// Store active HypenApp instances for cleanup
+const activeInstances = new WeakMap<
+  HTMLElement,
+  {
+    engine: RemoteEngine;
+    nodes: Map<string, HTMLElement>;
+  }
+>();
+
+export const hypenAppHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("div");
+    el.dataset.hypenType = "hypenapp";
+    el.style.display = "contents"; // Don't affect layout
+    return el;
+  },
+
+  applyProps(element: HTMLElement, props: Record<string, any>): void {
+    // Get URL from props (can be positional "0" or named "url")
+    const url = props["0"] || props.url;
+
+    if (!url || typeof url !== "string") {
+      console.error("[HypenApp] URL is required");
+      element.innerHTML = '<div style="color: red;">HypenApp: URL required</div>';
+      return;
+    }
+
+    // Check if already connected
+    const existing = activeInstances.get(element);
+    if (existing) {
+      // Already connected, don't reconnect
+      return;
+    }
+
+    // Create the remote engine
+    const engine = new RemoteEngine(url, {
+      autoReconnect: props.autoReconnect ?? true,
+      reconnectInterval: props.reconnectInterval ?? 3000,
+      maxReconnectAttempts: props.maxReconnectAttempts ?? 10,
+    });
+
+    // Map to track created nodes
+    const nodes = new Map<string, HTMLElement>();
+    let rootId: string | null = null;
+
+    // Store instance for cleanup
+    activeInstances.set(element, { engine, nodes });
+
+    // Set up patch handling
+    engine.onPatches((patches) => {
+      applyPatches(element, nodes, patches, engine, (id) => {
+        if (!rootId) rootId = id;
+      });
+    });
+
+    // Show loading state
+    element.innerHTML = '<div class="hypen-app-loading">Connecting...</div>';
+
+    // Connect
+    engine
+      .connect()
+      .then(() => {
+        // Clear loading state - patches will populate content
+        element.innerHTML = "";
+        console.log(`[HypenApp] Connected to ${url}`);
+      })
+      .catch((error) => {
+        element.innerHTML = `<div style="color: red;">HypenApp: Connection failed - ${error.message}</div>`;
+        console.error("[HypenApp] Connection failed:", error);
+      });
+
+    // Handle disconnection
+    engine.onDisconnect(() => {
+      console.log("[HypenApp] Disconnected");
+    });
+
+    engine.onError((error) => {
+      console.error("[HypenApp] Error:", error);
+    });
+
+    // Cleanup on element removal
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const removedNode of mutation.removedNodes) {
+          if (removedNode === element || (removedNode as Element).contains?.(element)) {
+            engine.disconnect();
+            activeInstances.delete(element);
+            observer.disconnect();
+            console.log("[HypenApp] Cleaned up");
+            return;
+          }
+        }
+      }
+    });
+
+    // Observe parent for removal
+    if (element.parentNode) {
+      observer.observe(element.parentNode, { childList: true, subtree: true });
+    }
+  },
+};
+
+/**
+ * Minimal patch application for HypenApp container
+ */
+function applyPatches(
+  container: HTMLElement,
+  nodes: Map<string, HTMLElement>,
+  patches: Patch[],
+  engine: RemoteEngine,
+  onRoot: (id: string) => void
+): void {
+  for (const patch of patches) {
+    switch (patch.type) {
+      case "create": {
+        const el = createElement((patch as any).element_type, patch.props || {});
+        el.dataset.hypenId = patch.id!;
+        (el as any).__hypenEngine = engine;
+        nodes.set(patch.id!, el);
+        break;
+      }
+
+      case "setProp": {
+        const el = nodes.get(patch.id!);
+        if (el) {
+          applyProp(el, patch.name!, patch.value);
+        }
+        break;
+      }
+
+      case "setText": {
+        const el = nodes.get(patch.id!);
+        if (el) {
+          el.textContent = patch.text!;
+        }
+        break;
+      }
+
+      case "insert": {
+        const parentId = (patch as any).parent_id;
+        const parent = parentId === "root" ? container : nodes.get(parentId);
+        const child = nodes.get(patch.id!);
+        const beforeId = (patch as any).before_id;
+
+        if (parent && child) {
+          if (parentId === "root") {
+            onRoot(patch.id!);
+          }
+
+          if (beforeId) {
+            const before = nodes.get(beforeId);
+            if (before && before.parentNode === parent) {
+              parent.insertBefore(child, before);
+            } else if (!parent.contains(child)) {
+              parent.appendChild(child);
+            }
+          } else if (!parent.contains(child)) {
+            parent.appendChild(child);
+          }
+        }
+        break;
+      }
+
+      case "move": {
+        const parentId = (patch as any).parent_id;
+        const parent = parentId === "root" ? container : nodes.get(parentId);
+        const child = nodes.get(patch.id!);
+        const beforeId = (patch as any).before_id;
+
+        if (parent && child) {
+          if (beforeId) {
+            const before = nodes.get(beforeId);
+            if (before && before.parentNode === parent) {
+              parent.insertBefore(child, before);
+            }
+          } else {
+            parent.appendChild(child);
+          }
+        }
+        break;
+      }
+
+      case "remove": {
+        const el = nodes.get(patch.id!);
+        if (el && el.parentNode) {
+          el.parentNode.removeChild(el);
+        }
+        nodes.delete(patch.id!);
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Create element by type
+ */
+function createElement(type: string, props: Record<string, any>): HTMLElement {
+  const normalizedType = type.toLowerCase();
+
+  // Map Hypen types to HTML elements
+  const tagMap: Record<string, string> = {
+    column: "div",
+    row: "div",
+    text: "span",
+    button: "button",
+    input: "input",
+    image: "img",
+    container: "div",
+    box: "div",
+    center: "div",
+    list: "div",
+    spacer: "div",
+    stack: "div",
+    divider: "hr",
+    grid: "div",
+    card: "div",
+    heading: "h2",
+    link: "a",
+    textarea: "textarea",
+    checkbox: "input",
+    select: "select",
+    slider: "input",
+    switch: "input",
+    spinner: "div",
+    badge: "span",
+    avatar: "img",
+    progressbar: "div",
+    video: "video",
+    audio: "audio",
+  };
+
+  const tag = tagMap[normalizedType] || "div";
+  const el = document.createElement(tag);
+  el.dataset.hypenType = normalizedType;
+
+  // Apply basic styles
+  if (normalizedType === "column") {
+    el.style.display = "flex";
+    el.style.flexDirection = "column";
+  } else if (normalizedType === "row") {
+    el.style.display = "flex";
+    el.style.flexDirection = "row";
+  } else if (normalizedType === "center") {
+    el.style.display = "flex";
+    el.style.alignItems = "center";
+    el.style.justifyContent = "center";
+  } else if (normalizedType === "text") {
+    // Text content from props
+    if (props["0"]) {
+      el.textContent = String(props["0"]);
+    }
+  } else if (normalizedType === "button") {
+    el.style.cursor = "pointer";
+  } else if (normalizedType === "checkbox" || normalizedType === "switch") {
+    (el as HTMLInputElement).type = "checkbox";
+  } else if (normalizedType === "slider") {
+    (el as HTMLInputElement).type = "range";
+  }
+
+  return el;
+}
+
+/**
+ * Apply a prop to an element
+ */
+function applyProp(el: HTMLElement, name: string, value: any): void {
+  // Text content
+  if (name === "0" || name === "text") {
+    el.textContent = String(value);
+    return;
+  }
+
+  // Style props
+  const styleProps: Record<string, string> = {
+    padding: "padding",
+    margin: "margin",
+    backgroundColor: "backgroundColor",
+    background: "background",
+    color: "color",
+    fontSize: "fontSize",
+    fontWeight: "fontWeight",
+    width: "width",
+    height: "height",
+    minWidth: "minWidth",
+    minHeight: "minHeight",
+    maxWidth: "maxWidth",
+    maxHeight: "maxHeight",
+    borderRadius: "borderRadius",
+    border: "border",
+    gap: "gap",
+    flex: "flex",
+    alignItems: "alignItems",
+    justifyContent: "justifyContent",
+    opacity: "opacity",
+    overflow: "overflow",
+  };
+
+  if (styleProps[name]) {
+    const cssValue = typeof value === "number" ? `${value}px` : String(value);
+    (el.style as any)[styleProps[name]] = cssValue;
+    return;
+  }
+
+  // Event handlers
+  if (name === "onClick" || name === "onclick") {
+    el.onclick = () => {
+      const engine = (el as any).__hypenEngine as RemoteEngine;
+      if (engine && typeof value === "string" && value.startsWith("@actions.")) {
+        const action = value.replace("@actions.", "");
+        engine.dispatchAction(action);
+      }
+    };
+    return;
+  }
+
+  // Other attributes
+  el.setAttribute(name, String(value));
+}
+
+/**
+ * Disconnect a HypenApp instance
+ */
+export function disconnectHypenApp(element: HTMLElement): void {
+  const instance = activeInstances.get(element);
+  if (instance) {
+    instance.engine.disconnect();
+    activeInstances.delete(element);
+  }
+}

package/src/dom/components/index.ts

@@ -79,6 +79,7 @@ export class ComponentRegistry {
     const { paragraphHandler } = require("./paragraph.js");
     const { routerHandler } = require("./router.js");
     const { routeHandler } = require("./route.js");
+    const { hypenAppHandler } = require("./hypenapp.js");
 
     this.register("column", columnHandler);
     this.register("row", rowHandler);
@@ -111,5 +112,6 @@ export class ComponentRegistry {
     this.register("paragraph", paragraphHandler);
     this.register("router", routerHandler);
     this.register("route", routeHandler);
+    this.register("hypenapp", hypenAppHandler);
   }
 }

package/src/dom/element-data.ts

@@ -0,0 +1,234 @@
+/**
+ * Type-Safe Element Data
+ *
+ * Provides strongly-typed access to Hypen-specific data attached to DOM elements.
+ * Eliminates `as any` casts throughout the codebase.
+ */
+
+import { type DisposableStack, getElementDisposables } from "@hypen/core";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Engine interface for dispatching actions
+ */
+export interface IEngine {
+  dispatchAction(name: string, payload?: unknown): void;
+}
+
+/**
+ * All Hypen-specific data attached to an element
+ */
+export interface HypenElementData {
+  /** Engine reference for action dispatch */
+  engine?: IEngine;
+  /** Target key for keyboard events (e.g., "Enter", "Escape") */
+  keyTarget?: string;
+  /** Set of registered event type:action pairs */
+  registeredEvents?: Set<string>;
+  /** Custom element metadata */
+  meta?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Private Storage
+// ============================================================================
+
+/**
+ * WeakMap to store Hypen data without polluting the element
+ */
+const elementDataMap = new WeakMap<HTMLElement, HypenElementData>();
+
+// ============================================================================
+// Core API
+// ============================================================================
+
+/**
+ * Get Hypen data for an element, creating if needed
+ */
+export function getHypenData(element: HTMLElement): HypenElementData {
+  let data = elementDataMap.get(element);
+  if (!data) {
+    data = {};
+    elementDataMap.set(element, data);
+  }
+  return data;
+}
+
+/**
+ * Check if element has Hypen data
+ */
+export function hasHypenData(element: HTMLElement): boolean {
+  return elementDataMap.has(element);
+}
+
+/**
+ * Clear Hypen data from an element
+ */
+export function clearHypenData(element: HTMLElement): void {
+  elementDataMap.delete(element);
+}
+
+// ============================================================================
+// Engine Access
+// ============================================================================
+
+/**
+ * Get the engine attached to an element
+ */
+export function getEngine(element: HTMLElement): IEngine | undefined {
+  return getHypenData(element).engine;
+}
+
+/**
+ * Set the engine on an element
+ */
+export function setEngine(element: HTMLElement, engine: IEngine): void {
+  getHypenData(element).engine = engine;
+}
+
+/**
+ * Find engine by walking up the DOM tree
+ */
+export function findEngine(element: HTMLElement): IEngine | undefined {
+  let current: HTMLElement | null = element;
+  while (current) {
+    const engine = getEngine(current);
+    if (engine) return engine;
+    current = current.parentElement;
+  }
+  return undefined;
+}
+
+// ============================================================================
+// Event Registration Tracking
+// ============================================================================
+
+/**
+ * Get registered events set for an element
+ */
+export function getRegisteredEvents(element: HTMLElement): Set<string> {
+  const data = getHypenData(element);
+  if (!data.registeredEvents) {
+    data.registeredEvents = new Set();
+  }
+  return data.registeredEvents;
+}
+
+/**
+ * Check if an event handler is registered
+ */
+export function isEventRegistered(element: HTMLElement, eventKey: string): boolean {
+  return getRegisteredEvents(element).has(eventKey);
+}
+
+/**
+ * Mark an event handler as registered
+ */
+export function registerEvent(element: HTMLElement, eventKey: string): void {
+  getRegisteredEvents(element).add(eventKey);
+}
+
+/**
+ * Unregister an event handler
+ */
+export function unregisterEvent(element: HTMLElement, eventKey: string): void {
+  getRegisteredEvents(element).delete(eventKey);
+}
+
+// ============================================================================
+// Keyboard Event Key Target
+// ============================================================================
+
+/**
+ * Get the target key for keyboard events
+ */
+export function getKeyTarget(element: HTMLElement): string | undefined {
+  return getHypenData(element).keyTarget;
+}
+
+/**
+ * Set the target key for keyboard events
+ */
+export function setKeyTarget(element: HTMLElement, key: string): void {
+  getHypenData(element).keyTarget = key;
+}
+
+// ============================================================================
+// Metadata
+// ============================================================================
+
+/**
+ * Get custom metadata value
+ */
+export function getMeta<T>(element: HTMLElement, key: string): T | undefined {
+  return getHypenData(element).meta?.[key] as T | undefined;
+}
+
+/**
+ * Set custom metadata value
+ */
+export function setMeta<T>(element: HTMLElement, key: string, value: T): void {
+  const data = getHypenData(element);
+  if (!data.meta) {
+    data.meta = {};
+  }
+  data.meta[key] = value;
+}
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+/**
+ * Dispose all resources attached to an element and clear data
+ * Call this when removing an element from the DOM
+ */
+export function disposeHypenElement(element: HTMLElement): void {
+  // Dispose any registered disposables
+  try {
+    const disposables = getElementDisposables(element);
+    disposables.dispose();
+  } catch {
+    // Ignore if no disposables
+  }
+
+  // Clear Hypen data
+  clearHypenData(element);
+}
+
+// ============================================================================
+// Legacy Compatibility Layer
+// ============================================================================
+
+/**
+ * Symbol-based legacy accessor (for backwards compatibility)
+ * Use the typed functions above instead when possible
+ */
+const HYPEN_ENGINE_SYMBOL = Symbol.for("hypen.engine");
+const REGISTERED_EVENTS_SYMBOL = Symbol.for("hypen.registeredEvents");
+const KEY_TARGET_SYMBOL = Symbol.for("hypen.keyTarget");
+
+/**
+ * Legacy accessor for engine (backwards compatible with existing code)
+ */
+export function getLegacyEngine(element: HTMLElement): IEngine | undefined {
+  // Try new storage first
+  const engine = getEngine(element);
+  if (engine) return engine;
+
+  // Fall back to legacy storage
+  return (element as any)[HYPEN_ENGINE_SYMBOL] ??
+    (element as any).__hypenEngine;
+}
+
+/**
+ * Legacy setter for engine (backwards compatible)
+ */
+export function setLegacyEngine(element: HTMLElement, engine: IEngine): void {
+  // Set in both locations for compatibility
+  setEngine(element, engine);
+  (element as any).__hypenEngine = engine;
+}

package/src/dom/renderer.ts

@@ -149,14 +149,17 @@ export class DOMRenderer {
   private onCreate(id: string, elementType: string, props: Record<string, any> | Map<string, any>): void {
     const propsObj = props instanceof Map ? Object.fromEntries(props) : props;
 
-    const element = this.components.createElement(elementType, propsObj);
+    let element = this.components.createElement(elementType, propsObj);
 
     if (!element) {
+      // For unknown component types, create a transparent container (div).
+      // This handles module wrappers (like "App") and custom components
+      // that aren't registered but should act as layout containers.
       const fallback = document.createElement("div");
-      fallback.dataset.hypenType = elementType;
-      fallback.textContent = `Unknown component: ${elementType}`;
-      this.nodes.set(id, fallback);
-      return;
+      fallback.dataset.hypenType = elementType.toLowerCase();
+      fallback.style.display = "contents"; // Make container transparent in layout
+      element = fallback;
+      console.log(`[Renderer] Unknown component "${elementType}" - using transparent container`);
     }
 
     element.dataset.hypenType = elementType.toLowerCase();

package/src/index.ts

@@ -38,6 +38,9 @@ export { ApplicatorRegistry } from "./dom/applicators/index.js";
 export { EventManager } from "./dom/events.js";
 export { RerenderTracker, type DebugConfig, defaultDebugConfig } from "./dom/debug.js";
 
+// HypenApp - Embed remote Hypen apps
+export { hypenAppHandler, disconnectHypenApp } from "./dom/components/hypenapp.js";
+
 // ============================================================================
 // CANVAS RENDERER
 // ============================================================================