@hypen-space/core 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,373 @@
+# @hypen-space/core
+
+The reactive runtime for Hypen - a declarative UI language that separates what your UI looks like from how it behaves.
+
+## What is Hypen?
+
+Hypen lets you write UI templates in a clean, declarative syntax:
+
+```hypen
+Column {
+  Text("Hello, ${state.user.name}!")
+  Button(onClick: @actions.logout) {
+    Text("Sign Out")
+  }
+}
+```
+
+The `@hypen-space/core` package provides the engine that:
+
+1. **Parses** your Hypen templates
+2. **Tracks** reactive state bindings (like `${state.user.name}`)
+3. **Generates patches** when state changes (instead of re-rendering everything)
+4. **Dispatches actions** triggered from the UI (like `@actions.logout`)
+
+You provide a renderer that applies those patches to your platform (DOM, Canvas, Native, etc).
+
+## Installation
+
+```bash
+npm install @hypen-space/core
+# or
+bun add @hypen-space/core
+```
+
+## Core Concepts
+
+### Templates
+
+Hypen templates describe your UI structure. Components can have:
+
+- **Arguments**: `Text("Hello")` or `Button(disabled: true)`
+- **Children**: Nested inside `{ }` braces
+- **Applicators**: Chained styling like `.padding(16).color(blue)`
+
+### State Bindings
+
+Use `${state.path}` to bind template values to your module's state:
+
+```hypen
+Text("Count: ${state.count}")
+Text("User: ${state.user.name}")
+```
+
+When state changes, only the affected parts of the UI update.
+
+### Actions
+
+Use `@actions.name` to dispatch events from the UI to your module:
+
+```hypen
+Button(onClick: @actions.increment) { Text("+") }
+Button(onClick: @actions.submitForm) { Text("Submit") }
+```
+
+### Patches
+
+The engine doesn't manipulate the UI directly. Instead, it emits **patches** - minimal instructions describing what changed:
+
+```typescript
+{ type: "Create", id: "1", elementType: "Text", props: { text: "Hello" } }
+{ type: "SetProp", id: "1", name: "text", value: "Hello, World" }
+{ type: "Remove", id: "1" }
+```
+
+Your renderer applies these patches to the actual platform.
+
+## Quick Start
+
+```typescript
+import { Engine, app } from "@hypen-space/core";
+
+// 1. Define your module's state and actions
+const counter = app
+  .defineState({ count: 0 })
+  .onAction("increment", ({ state }) => state.count++)
+  .onAction("decrement", ({ state }) => state.count--)
+  .build();
+
+// 2. Initialize the engine
+const engine = new Engine();
+await engine.init();
+
+// 3. Connect your renderer
+engine.setRenderCallback((patches) => {
+  myRenderer.applyPatches(patches);
+});
+
+// 4. Register the module and render
+engine.setModule("counter", counter.actions, counter.stateKeys, counter.initialState);
+
+engine.renderSource(`
+  Column {
+    Text("Count: \${state.count}")
+    Row {
+      Button(onClick: @actions.decrement) { Text("-") }
+      Button(onClick: @actions.increment) { Text("+") }
+    }
+  }
+`);
+```
+
+## Modules
+
+Modules manage state and handle actions. Use the `app` builder to define them:
+
+```typescript
+import { app } from "@hypen-space/core";
+
+interface UserState {
+  user: { id: string; name: string } | null;
+  loading: boolean;
+}
+
+const userModule = app
+  .defineState<UserState>({ user: null, loading: false })
+
+  // Called when module is created
+  .onCreated(async ({ state, next }) => {
+    state.loading = true;
+    next(); // Sync state changes to engine
+  })
+
+  // Handle actions dispatched from UI
+  .onAction("loadUser", async ({ state, action, next }) => {
+    const userId = action.payload?.id;
+    state.user = await fetchUser(userId);
+    state.loading = false;
+    next();
+  })
+
+  .onAction("logout", ({ state, next }) => {
+    state.user = null;
+    next();
+  })
+
+  // Called when module is destroyed
+  .onDestroyed(({ state }) => {
+    console.log("Cleanup");
+  })
+
+  .build();
+```
+
+The `next()` callback synchronizes state changes with the engine after async operations.
+
+## State
+
+State is automatically tracked via Proxy. Mutations trigger UI updates:
+
+```typescript
+import { createObservableState, batchStateUpdates, getStateSnapshot } from "@hypen-space/core";
+
+const state = createObservableState({ count: 0, items: [] }, {
+  onChange: (path, oldVal, newVal) => {
+    console.log(`${path.join(".")} changed: ${oldVal} -> ${newVal}`);
+  }
+});
+
+// Direct mutations are tracked
+state.count = 5;
+state.items.push("item");
+
+// Batch multiple updates into one render cycle
+batchStateUpdates(state, () => {
+  state.count = 10;
+  state.items = ["a", "b", "c"];
+});
+
+// Get an immutable snapshot
+const snapshot = getStateSnapshot(state);
+```
+
+## Custom Renderers
+
+Extend `BaseRenderer` to render to any platform:
+
+```typescript
+import { BaseRenderer } from "@hypen-space/core";
+
+class MyRenderer extends BaseRenderer {
+  protected onCreate(id: string, type: string, props: Record<string, any>) {
+    // Create an element
+  }
+  protected onSetProp(id: string, name: string, value: any) {
+    // Update a property
+  }
+  protected onSetText(id: string, text: string) {
+    // Set text content
+  }
+  protected onInsert(parentId: string, id: string, beforeId?: string) {
+    // Insert into parent
+  }
+  protected onMove(parentId: string, id: string, beforeId?: string) {
+    // Reorder element
+  }
+  protected onRemove(id: string) {
+    // Remove element
+  }
+}
+```
+
+See `@hypen-space/web` for a DOM renderer implementation.
+
+## Routing
+
+Built-in hash or pathname routing:
+
+```typescript
+import { HypenRouter } from "@hypen-space/core";
+
+const router = new HypenRouter();
+
+router.navigate("/products/123");
+
+router.subscribe((state) => {
+  console.log("Path:", state.currentPath);
+  console.log("Params:", state.params);   // { id: "123" }
+  console.log("Query:", state.query);
+});
+```
+
+Use built-in components in templates:
+
+```hypen
+Router {
+  Route(path: "/") { HomePage }
+  Route(path: "/products/:id") { ProductPage }
+}
+Link(to: "/products/42") { Text("View Product") }
+```
+
+## Component Discovery
+
+For larger apps, organize components as files and auto-discover them:
+
+```typescript
+import { discoverComponents, loadDiscoveredComponents } from "@hypen-space/core";
+
+const components = await discoverComponents("./src/components");
+const loaded = await loadDiscoveredComponents(components);
+```
+
+Supported file patterns:
+
+```
+Counter/
+├── component.hypen    # Template
+└── component.ts       # Module
+
+Counter.hypen          # Or sibling files
+Counter.ts
+
+Counter/
+├── index.hypen        # Or index-based
+└── index.ts
+```
+
+Watch for changes (hot reload):
+
+```typescript
+import { watchComponents } from "@hypen-space/core";
+
+const watcher = watchComponents("./src/components", {
+  onUpdate: (c) => console.log("Updated:", c.name),
+});
+```
+
+## Component Loader
+
+Register components programmatically:
+
+```typescript
+import { componentLoader, ComponentLoader } from "@hypen-space/core";
+
+// Global loader
+componentLoader.register("Counter", counterModule, counterTemplate);
+componentLoader.get("Counter");
+componentLoader.has("Counter");
+
+// Or create your own
+const loader = new ComponentLoader();
+await loader.loadFromComponentsDir("./src/components");
+```
+
+## Remote UI
+
+Connect to a Hypen server for server-driven UI:
+
+```typescript
+import { RemoteEngine } from "@hypen-space/core";
+
+const remote = new RemoteEngine("ws://localhost:3000", {
+  autoReconnect: true,
+});
+
+remote
+  .onPatches((patches) => renderer.applyPatches(patches))
+  .onStateUpdate((state) => console.log("Server state:", state))
+  .onConnect(() => console.log("Connected"));
+
+await remote.connect();
+remote.dispatchAction("loadData", { page: 1 });
+```
+
+## Global Context
+
+Share state and events across modules:
+
+```typescript
+import { HypenGlobalContext } from "@hypen-space/core";
+
+const context = new HypenGlobalContext();
+
+context.registerModule("auth", authModule);
+context.registerModule("cart", cartModule);
+
+// Cross-module access
+const user = context.getModule("auth").getState().user;
+
+// Event bus
+context.on("userLoggedIn", (user) => { /* ... */ });
+context.emit("userLoggedIn", { id: "1", name: "Ian" });
+```
+
+## Browser vs Node.js
+
+```typescript
+// Node.js / Bundler - WASM loads automatically
+import { Engine } from "@hypen-space/core";
+const engine = new Engine();
+await engine.init();
+
+// Browser - specify WASM path
+import { BrowserEngine } from "@hypen-space/core";
+const engine = new BrowserEngine();
+await engine.init({ wasmPath: "/hypen_engine_bg.wasm" });
+```
+
+## Package Exports
+
+| Export | Description |
+|--------|-------------|
+| `@hypen-space/core` | Main entry point |
+| `@hypen-space/core/engine` | Low-level WASM engine |
+| `@hypen-space/core/engine/browser` | Browser-optimized engine |
+| `@hypen-space/core/app` | Module builder |
+| `@hypen-space/core/state` | Observable state utilities |
+| `@hypen-space/core/renderer` | Abstract renderer |
+| `@hypen-space/core/router` | Routing system |
+| `@hypen-space/core/context` | Global context |
+| `@hypen-space/core/remote` | Remote UI protocol |
+| `@hypen-space/core/loader` | Component loader |
+| `@hypen-space/core/discovery` | Component discovery |
+| `@hypen-space/core/components` | Built-in Router, Route, Link |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript 5+ (optional)
+
+## License
+
+MIT

package/dist/src/components/builtin.js

@@ -0,0 +1,89 @@
+import {
+  app
+} from "../app.js";
+import"../state.js";
+import"../../chunk-5va59f7m.js";
+
+// src/components/builtin.ts
+var Router = app.defineState({
+  currentPath: "/",
+  matchedRoute: null,
+  routeParams: {}
+}, { name: "__Router" }).onCreated((state, context) => {
+  if (!context) {
+    console.error("[Router] Requires global context");
+    return;
+  }
+  const router = context.__router;
+  if (!router) {
+    console.error("[Router] Router not found in context");
+    return;
+  }
+  const hypenEngine = context.__hypenEngine;
+  const updateRouteVisibility = async (currentPath) => {
+    const routeElements = document.querySelectorAll('[data-hypen-type="route"]');
+    let matchFound = false;
+    for (let index = 0;index < routeElements.length; index++) {
+      const routeEl = routeElements[index];
+      const htmlEl = routeEl;
+      const routePath = htmlEl.dataset.routePath || "/";
+      const isMatch = routePath === currentPath;
+      htmlEl.style.display = isMatch ? "flex" : "none";
+      if (isMatch) {
+        matchFound = true;
+        const componentName = htmlEl.dataset.routeComponent;
+        const isLazy = htmlEl.dataset.routeLazy === "true";
+        const hasContent = htmlEl.children.length > 0;
+        if (componentName && !hasContent && hypenEngine) {
+          try {
+            await hypenEngine.renderLazyRoute(routePath, componentName, htmlEl);
+          } catch (err) {
+            console.error(`[Router] Failed to render route ${routePath}:`, err);
+          }
+        }
+      }
+    }
+    if (!matchFound) {
+      console.warn(`[Router] No route matched path: ${currentPath}. Available routes:`, Array.from(routeElements).map((el) => el.dataset.routePath));
+    }
+  };
+  setTimeout(() => {
+    updateRouteVisibility(state.currentPath);
+  }, 100);
+  router.onNavigate((routeState) => {
+    state.currentPath = routeState.currentPath;
+    state.routeParams = routeState.params;
+    updateRouteVisibility(routeState.currentPath);
+  });
+}).build();
+var Route = app.defineState({}, { name: "__Route" }).build();
+var Link = app.defineState({
+  to: "/",
+  isActive: false
+}, { name: "__Link" }).onAction("navigate", ({ state, context }) => {
+  const router = context?.__router;
+  if (!router) {
+    console.error("[Link] Requires router context");
+    return;
+  }
+  const targetPath = state.to;
+  router.push(targetPath);
+}).onCreated((state, context) => {
+  if (!context)
+    return;
+  const router = context.__router;
+  if (router) {
+    router.onNavigate((routeState) => {
+      state.isActive = routeState.currentPath === state.to;
+    });
+  }
+}).build();
+export {
+  Router,
+  Route,
+  Link
+};
+
+export { Router, Route, Link };
+
+//# debugId=DCABC4D99E5064EE64756E2164756E21

package/dist/src/components/builtin.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/components/builtin.ts"],
+  "sourcesContent": [
+    "/**\n * Built-in Hypen Components\n * Framework-provided components like Router and Route\n */\n\nimport { app } from \"../app.js\";\nimport type { HypenRouter } from \"../router.js\";\n\n/**\n * Router Component\n * Automatically matches routes and renders the appropriate child Route\n *\n * Usage in Hypen DSL:\n * Router {\n *   Route(path: \"/\") { HomePage }\n *   Route(path: \"/products\") { ProductList }\n *   Route(path: \"/users/:id\") { UserProfile }\n * }\n */\nexport const Router = app\n  .defineState(\n    {\n      currentPath: \"/\",\n      matchedRoute: null as any,\n      routeParams: {} as Record<string, string>,\n    },\n    { name: \"__Router\" }\n  )\n  .onCreated((state, context) => {\n    if (!context) {\n      console.error(\"[Router] Requires global context\");\n      return;\n    }\n\n    // Subscribe to router changes\n    const router = (context as any).__router as HypenRouter;\n    if (!router) {\n      console.error(\"[Router] Router not found in context\");\n      return;\n    }\n\n    // Get access to the Hypen engine for lazy rendering\n    const hypenEngine = (context as any).__hypenEngine;\n\n    // Function to render only the matching route\n    const updateRouteVisibility = async (currentPath: string) => {\n      // Find all Route elements in the DOM\n      const routeElements = document.querySelectorAll(\n        '[data-hypen-type=\"route\"]'\n      );\n\n      let matchFound = false;\n\n      for (let index = 0; index < routeElements.length; index++) {\n        const routeEl = routeElements[index];\n        const htmlEl = routeEl as HTMLElement;\n        const routePath = htmlEl.dataset.routePath || \"/\";\n\n        // Simple path matching (exact match for now)\n        const isMatch = routePath === currentPath;\n\n        // Only show the matching route, hide all others\n        htmlEl.style.display = isMatch ? \"flex\" : \"none\";\n\n        if (isMatch) {\n          matchFound = true;\n\n          // Check if this route needs to be rendered\n          const componentName = htmlEl.dataset.routeComponent;\n          const isLazy = htmlEl.dataset.routeLazy === \"true\";\n          const hasContent = htmlEl.children.length > 0;\n\n          // Render if route has no content and has a component name\n          if (componentName && !hasContent && hypenEngine) {\n            try {\n              await hypenEngine.renderLazyRoute(\n                routePath,\n                componentName,\n                htmlEl\n              );\n            } catch (err) {\n              console.error(`[Router] Failed to render route ${routePath}:`, err);\n            }\n          }\n        }\n      }\n\n      if (!matchFound) {\n        console.warn(\n          `[Router] No route matched path: ${currentPath}. Available routes:`,\n          Array.from(routeElements).map(\n            (el: Element) => (el as HTMLElement).dataset.routePath\n          )\n        );\n      }\n    };\n\n    // Initial route visibility (after DOM is ready)\n    setTimeout(() => {\n      updateRouteVisibility(state.currentPath);\n    }, 100);\n\n    router.onNavigate((routeState) => {\n      state.currentPath = routeState.currentPath;\n      state.routeParams = routeState.params;\n\n      // Update route visibility when path changes\n      updateRouteVisibility(routeState.currentPath);\n    });\n  })\n  .build();\n\n/**\n * Route Component\n * Defines a route pattern and its content\n * This is just a marker component - Router processes it\n *\n * Props:\n * - path: string - Route pattern (e.g., \"/\", \"/users/:id\", \"/dashboard/*\")\n *\n * Usage:\n * Route(path: \"/products\") {\n *   ProductList\n * }\n */\nexport const Route = app.defineState({}, { name: \"__Route\" }).build();\n\n/**\n * Navigation Link Component\n * Navigates to a route when clicked\n *\n * Props:\n * - to: string - Target path\n *\n * Usage:\n * Link(to: \"/products\") {\n *   Text(\"View Products\")\n * }\n */\nexport const Link = app\n  .defineState(\n    {\n      to: \"/\",\n      isActive: false,\n    },\n    { name: \"__Link\" }\n  )\n  .onAction(\"navigate\", ({ state, context }) => {\n    const router = (context as any)?.__router as HypenRouter;\n    if (!router) {\n      console.error(\"[Link] Requires router context\");\n      return;\n    }\n\n    const targetPath = state.to;\n    router.push(targetPath);\n  })\n  .onCreated((state, context) => {\n    if (!context) return;\n\n    // Check if current path matches this link's target\n    const router = (context as any).__router as HypenRouter;\n    if (router) {\n      router.onNavigate((routeState) => {\n        state.isActive = routeState.currentPath === state.to;\n      });\n    }\n  })\n  .build();\n"
+  ],
+  "mappings": ";;;;;;;AAmBO,IAAM,SAAS,IACnB,YACC;AAAA,EACE,aAAa;AAAA,EACb,cAAc;AAAA,EACd,aAAa,CAAC;AAChB,GACA,EAAE,MAAM,WAAW,CACrB,EACC,UAAU,CAAC,OAAO,YAAY;AAAA,EAC7B,IAAI,CAAC,SAAS;AAAA,IACZ,QAAQ,MAAM,kCAAkC;AAAA,IAChD;AAAA,EACF;AAAA,EAGA,MAAM,SAAU,QAAgB;AAAA,EAChC,IAAI,CAAC,QAAQ;AAAA,IACX,QAAQ,MAAM,sCAAsC;AAAA,IACpD;AAAA,EACF;AAAA,EAGA,MAAM,cAAe,QAAgB;AAAA,EAGrC,MAAM,wBAAwB,OAAO,gBAAwB;AAAA,IAE3D,MAAM,gBAAgB,SAAS,iBAC7B,2BACF;AAAA,IAEA,IAAI,aAAa;AAAA,IAEjB,SAAS,QAAQ,EAAG,QAAQ,cAAc,QAAQ,SAAS;AAAA,MACzD,MAAM,UAAU,cAAc;AAAA,MAC9B,MAAM,SAAS;AAAA,MACf,MAAM,YAAY,OAAO,QAAQ,aAAa;AAAA,MAG9C,MAAM,UAAU,cAAc;AAAA,MAG9B,OAAO,MAAM,UAAU,UAAU,SAAS;AAAA,MAE1C,IAAI,SAAS;AAAA,QACX,aAAa;AAAA,QAGb,MAAM,gBAAgB,OAAO,QAAQ;AAAA,QACrC,MAAM,SAAS,OAAO,QAAQ,cAAc;AAAA,QAC5C,MAAM,aAAa,OAAO,SAAS,SAAS;AAAA,QAG5C,IAAI,iBAAiB,CAAC,cAAc,aAAa;AAAA,UAC/C,IAAI;AAAA,YACF,MAAM,YAAY,gBAChB,WACA,eACA,MACF;AAAA,YACA,OAAO,KAAK;AAAA,YACZ,QAAQ,MAAM,mCAAmC,cAAc,GAAG;AAAA;AAAA,QAEtE;AAAA,MACF;AAAA,IACF;AAAA,IAEA,IAAI,CAAC,YAAY;AAAA,MACf,QAAQ,KACN,mCAAmC,kCACnC,MAAM,KAAK,aAAa,EAAE,IACxB,CAAC,OAAiB,GAAmB,QAAQ,SAC/C,CACF;AAAA,IACF;AAAA;AAAA,EAIF,WAAW,MAAM;AAAA,IACf,sBAAsB,MAAM,WAAW;AAAA,KACtC,GAAG;AAAA,EAEN,OAAO,WAAW,CAAC,eAAe;AAAA,IAChC,MAAM,cAAc,WAAW;AAAA,IAC/B,MAAM,cAAc,WAAW;AAAA,IAG/B,sBAAsB,WAAW,WAAW;AAAA,GAC7C;AAAA,CACF,EACA,MAAM;AAeF,IAAM,QAAQ,IAAI,YAAY,CAAC,GAAG,EAAE,MAAM,UAAU,CAAC,EAAE,MAAM;AAc7D,IAAM,OAAO,IACjB,YACC;AAAA,EACE,IAAI;AAAA,EACJ,UAAU;AACZ,GACA,EAAE,MAAM,SAAS,CACnB,EACC,SAAS,YAAY,GAAG,OAAO,cAAc;AAAA,EAC5C,MAAM,SAAU,SAAiB;AAAA,EACjC,IAAI,CAAC,QAAQ;AAAA,IACX,QAAQ,MAAM,gCAAgC;AAAA,IAC9C;AAAA,EACF;AAAA,EAEA,MAAM,aAAa,MAAM;AAAA,EACzB,OAAO,KAAK,UAAU;AAAA,CACvB,EACA,UAAU,CAAC,OAAO,YAAY;AAAA,EAC7B,IAAI,CAAC;AAAA,IAAS;AAAA,EAGd,MAAM,SAAU,QAAgB;AAAA,EAChC,IAAI,QAAQ;AAAA,IACV,OAAO,WAAW,CAAC,eAAe;AAAA,MAChC,MAAM,WAAW,WAAW,gBAAgB,MAAM;AAAA,KACnD;AAAA,EACH;AAAA,CACD,EACA,MAAM;",
+  "debugId": "DCABC4D99E5064EE64756E2164756E21",
+  "names": []
+}