@constela/runtime 0.12.0 → 0.12.2

package/README.md

@@ -40,6 +40,129 @@ Becomes an interactive app with:
 
 ## Features
 
+### Fine-grained State Updates (setPath)
+
+Update nested values without replacing entire arrays:
+
+```json
+{
+  "do": "setPath",
+  "target": "posts",
+  "path": [5, "liked"],
+  "value": { "expr": "lit", "value": true }
+}
+```
+
+Dynamic path with variables:
+
+```json
+{
+  "do": "setPath",
+  "target": "posts",
+  "path": { "expr": "var", "name": "payload", "path": "index" },
+  "field": "liked",
+  "value": { "expr": "lit", "value": true }
+}
+```
+
+### String Concatenation (concat)
+
+Build dynamic strings from multiple expressions:
+
+```json
+{
+  "expr": "concat",
+  "items": [
+    { "expr": "lit", "value": "/users/" },
+    { "expr": "var", "name": "userId" },
+    { "expr": "lit", "value": "/profile" }
+  ]
+}
+```
+
+Useful for:
+- Dynamic URLs: `/api/posts/{id}`
+- CSS class names: `btn btn-{variant}`
+- Formatted messages: `Hello, {name}!`
+
+### Object Payloads for Event Handlers
+
+Pass multiple values to actions with object-shaped payloads:
+
+```json
+{
+  "kind": "element",
+  "tag": "button",
+  "props": {
+    "onClick": {
+      "event": "click",
+      "action": "toggleLike",
+      "payload": {
+        "index": { "expr": "var", "name": "index" },
+        "postId": { "expr": "var", "name": "post", "path": "id" },
+        "currentLiked": { "expr": "var", "name": "post", "path": "liked" }
+      }
+    }
+  }
+}
+```
+
+Each expression field in the payload is evaluated when the event fires. The action receives the evaluated object:
+
+```json
+{ "index": 5, "postId": "abc123", "currentLiked": true }
+```
+
+### Key-based List Diffing
+
+Efficient list updates - only changed items re-render:
+
+```json
+{
+  "kind": "each",
+  "items": { "expr": "state", "name": "posts" },
+  "as": "post",
+  "key": { "expr": "var", "name": "post", "path": "id" },
+  "body": { ... }
+}
+```
+
+Benefits:
+- Add/remove items: Only affected DOM nodes change
+- Reorder: DOM nodes move without recreation
+- Update item: Only that item re-renders
+- Input state preserved during updates
+
+### WebSocket Connections
+
+Real-time data with declarative WebSocket:
+
+```json
+{
+  "connections": {
+    "chat": {
+      "type": "websocket",
+      "url": "wss://api.example.com/ws",
+      "onMessage": { "action": "handleMessage" },
+      "onOpen": { "action": "connectionOpened" },
+      "onClose": { "action": "connectionClosed" }
+    }
+  }
+}
+```
+
+Send messages:
+
+```json
+{ "do": "send", "connection": "chat", "data": { "expr": "state", "name": "inputText" } }
+```
+
+Close connection:
+
+```json
+{ "do": "close", "connection": "chat" }
+```
+
 ### Markdown Rendering
 
 ```json
@@ -148,17 +271,43 @@ interface AppInstance {
 ### Reactive Primitives
 
 ```typescript
-import { createSignal, createEffect } from '@constela/runtime';
+import { createSignal, createEffect, createComputed } from '@constela/runtime';
 
 const count = createSignal(0);
 count.get();  // Read
 count.set(1); // Write
 
+// Computed values with automatic dependency tracking
+const doubled = createComputed(() => count.get() * 2);
+doubled.get(); // Returns memoized value
+
 const cleanup = createEffect(() => {
   console.log(`Count: ${count.get()}`);
 });
 ```
 
+### TypedStateStore (TypeScript)
+
+Type-safe state access for TypeScript developers:
+
+```typescript
+import { createTypedStateStore } from '@constela/runtime';
+
+interface AppState {
+  posts: { id: number; liked: boolean }[];
+  filter: string;
+}
+
+const state = createTypedStateStore<AppState>({
+  posts: { type: 'list', initial: [] },
+  filter: { type: 'string', initial: '' },
+});
+
+state.get('posts');  // Type: { id: number; liked: boolean }[]
+state.set('filter', 'recent'); // OK
+state.set('filter', 123);      // TypeScript error
+```
+
 ## License
 
 MIT

package/dist/index.js

@@ -422,12 +422,40 @@ function evaluate(expr, ctx) {
     }
     case "style":
       return evaluateStyle(expr, ctx);
+    case "concat": {
+      return expr.items.map((item) => {
+        const val = evaluate(item, ctx);
+        return val == null ? "" : String(val);
+      }).join("");
+    }
     default: {
       const _exhaustiveCheck = expr;
       throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustiveCheck)}`);
     }
   }
 }
+function isExpression(value) {
+  return typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, "expr") && typeof value.expr === "string";
+}
+function evaluatePayload(payload, ctx) {
+  if (isExpression(payload)) {
+    return evaluate(payload, ctx);
+  }
+  if (typeof payload === "object" && payload !== null) {
+    const forbiddenKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+    const result = {};
+    for (const [key2, value] of Object.entries(payload)) {
+      if (forbiddenKeys.has(key2)) continue;
+      if (isExpression(value)) {
+        result[key2] = evaluate(value, ctx);
+      } else {
+        result[key2] = value;
+      }
+    }
+    return result;
+  }
+  return payload;
+}
 function getNestedValue(obj, path) {
   const forbiddenKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
   const parts = path.split(".");
@@ -13165,7 +13193,7 @@ function renderElement(node, ctx) {
             }
             let payload = void 0;
             if (handler.payload) {
-              payload = evaluate(handler.payload, {
+              payload = evaluatePayload(handler.payload, {
                 state: ctx.state,
                 locals: { ...ctx.locals, ...eventLocals },
                 ...ctx.imports && { imports: ctx.imports }
@@ -13314,6 +13342,18 @@ function createReactiveLocals(baseLocals, itemKey, itemSignal, indexKey, indexSi
       if (prop === itemKey) return true;
       if (indexKey && prop === indexKey) return true;
       return prop in target;
+    },
+    ownKeys(target) {
+      const keys = Reflect.ownKeys(target);
+      if (!keys.includes(itemKey)) keys.push(itemKey);
+      if (indexKey && !keys.includes(indexKey)) keys.push(indexKey);
+      return keys;
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      if (prop === itemKey || indexKey && prop === indexKey) {
+        return { enumerable: true, configurable: true };
+      }
+      return Reflect.getOwnPropertyDescriptor(target, prop);
     }
   });
 }
@@ -13588,6 +13628,18 @@ function createReactiveLocals2(baseLocals, itemSignal, indexSignal, itemName, in
       if (prop === itemName) return true;
       if (indexName && prop === indexName) return true;
       return prop in target;
+    },
+    ownKeys(target) {
+      const keys = Reflect.ownKeys(target);
+      if (!keys.includes(itemName)) keys.push(itemName);
+      if (indexName && !keys.includes(indexName)) keys.push(indexName);
+      return keys;
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      if (prop === itemName || indexName && prop === indexName) {
+        return { enumerable: true, configurable: true };
+      }
+      return Reflect.getOwnPropertyDescriptor(target, prop);
     }
   });
 }
@@ -13711,7 +13763,7 @@ function hydrateElement(node, el, ctx) {
             }
             let payload = void 0;
             if (handler.payload) {
-              payload = evaluate(handler.payload, {
+              payload = evaluatePayload(handler.payload, {
                 state: ctx.state,
                 locals: { ...ctx.locals, ...eventLocals },
                 ...ctx.imports && { imports: ctx.imports },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/runtime",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Runtime DOM renderer for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,8 +18,8 @@
     "dompurify": "^3.3.1",
     "marked": "^17.0.1",
     "shiki": "^3.20.0",
-    "@constela/compiler": "0.9.0",
-    "@constela/core": "0.9.0"
+    "@constela/compiler": "0.9.1",
+    "@constela/core": "0.9.1"
   },
   "devDependencies": {
     "@types/dompurify": "^3.2.0",
@@ -29,7 +29,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^2.0.0",
-    "@constela/server": "5.0.0"
+    "@constela/server": "5.0.1"
   },
   "engines": {
     "node": ">=20.0.0"