@constela/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Constela Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { CompiledExpression, CompiledAction, CompiledNode, CompiledProgram } from '@constela/compiler';
+
+interface Signal<T> {
+    get(): T;
+    set(value: T): void;
+    subscribe?(fn: (value: T) => void): () => void;
+}
+declare function createSignal<T>(initial: T): Signal<T>;
+
+/**
+ * Effect - Reactive side effect
+ *
+ * An effect runs a function and automatically tracks signal dependencies.
+ * When any tracked signal changes, the effect re-runs.
+ */
+type CleanupFn = () => void;
+type EffectFn = () => void | CleanupFn;
+declare function createEffect(fn: EffectFn): () => void;
+
+/**
+ * StateStore - Centralized state management
+ *
+ * Creates signals for each state field defined in the program.
+ * Provides get/set methods for accessing state.
+ */
+interface StateStore {
+    get(name: string): unknown;
+    set(name: string, value: unknown): void;
+}
+interface StateDefinition {
+    type: string;
+    initial: unknown;
+}
+declare function createStateStore(definitions: Record<string, StateDefinition>): StateStore;
+
+/**
+ * Expression Evaluator - Evaluates compiled expressions
+ *
+ * Supports:
+ * - Literal values (lit)
+ * - State reads (state)
+ * - Variable reads (var)
+ * - Binary operations (bin)
+ * - Not operation (not)
+ */
+
+interface EvaluationContext {
+    state: StateStore;
+    locals: Record<string, unknown>;
+}
+declare function evaluate(expr: CompiledExpression, ctx: EvaluationContext): unknown;
+
+/**
+ * Action Executor - Executes compiled action steps
+ *
+ * Supports:
+ * - set: Update state with value
+ * - update: Increment/decrement numbers, push/pop/remove for arrays
+ * - fetch: Make HTTP requests with onSuccess/onError handlers
+ */
+
+interface ActionContext {
+    state: StateStore;
+    actions: Record<string, CompiledAction>;
+    locals: Record<string, unknown>;
+    eventPayload?: unknown;
+}
+declare function executeAction(action: CompiledAction, ctx: ActionContext): Promise<void>;
+
+/**
+ * Renderer - DOM rendering for compiled view nodes
+ *
+ * Renders:
+ * - element: Creates DOM elements with props and event handlers
+ * - text: Creates text nodes
+ * - if: Conditional rendering with reactive updates
+ * - each: List rendering with reactive updates
+ */
+
+interface RenderContext {
+    state: StateStore;
+    actions: Record<string, CompiledAction>;
+    locals: Record<string, unknown>;
+    cleanups?: (() => void)[];
+}
+declare function render(node: CompiledNode, ctx: RenderContext): Node;
+
+/**
+ * App - Main entry point for creating Constela applications
+ *
+ * Creates a reactive application from a CompiledProgram and mounts it to the DOM.
+ */
+
+interface AppInstance {
+    destroy(): void;
+    setState(name: string, value: unknown): void;
+    getState(name: string): unknown;
+}
+declare function createApp(program: CompiledProgram, mount: HTMLElement): AppInstance;
+
+export { type ActionContext, type AppInstance, type EvaluationContext, type RenderContext, type Signal, type StateStore, createApp, createEffect, createSignal, createStateStore, evaluate, executeAction, render };

package/dist/index.js

@@ -0,0 +1,583 @@
+// src/reactive/signal.ts
+var currentEffect = null;
+var trackingEnabled = true;
+var effectDependencies = /* @__PURE__ */ new Map();
+function setCurrentEffect(effect) {
+  currentEffect = effect;
+}
+function registerEffectCleanup(effect) {
+  if (!effectDependencies.has(effect)) {
+    effectDependencies.set(effect, /* @__PURE__ */ new Set());
+  }
+}
+function cleanupEffect(effect) {
+  const deps = effectDependencies.get(effect);
+  if (deps) {
+    for (const signalSubscribers of deps) {
+      signalSubscribers.delete(effect);
+    }
+    deps.clear();
+    effectDependencies.delete(effect);
+  }
+}
+function createSignal(initial) {
+  let value = initial;
+  const subscribers = /* @__PURE__ */ new Set();
+  const effectSubscribers = /* @__PURE__ */ new Set();
+  const signal = {
+    get() {
+      if (trackingEnabled && currentEffect) {
+        effectSubscribers.add(currentEffect);
+        const deps = effectDependencies.get(currentEffect);
+        if (deps) {
+          deps.add(effectSubscribers);
+        }
+      }
+      if (Array.isArray(value)) {
+        return [...value];
+      }
+      return value;
+    },
+    set(newValue) {
+      value = newValue;
+      subscribers.forEach((fn) => fn(newValue));
+      const effects = [...effectSubscribers];
+      effects.forEach((effect) => effect());
+    },
+    subscribe(fn) {
+      subscribers.add(fn);
+      return () => {
+        subscribers.delete(fn);
+      };
+    }
+  };
+  return signal;
+}
+
+// src/reactive/effect.ts
+var effectStack = [];
+function createEffect(fn) {
+  let cleanup;
+  let isDisposed = false;
+  const execute = () => {
+    if (isDisposed) return;
+    if (typeof cleanup === "function") {
+      cleanup();
+      cleanup = void 0;
+    }
+    cleanupEffect(execute);
+    effectStack.push(execute);
+    setCurrentEffect(execute);
+    registerEffectCleanup(execute);
+    try {
+      const result = fn();
+      if (typeof result === "function") {
+        cleanup = result;
+      }
+    } finally {
+      effectStack.pop();
+      const parentEffect = effectStack[effectStack.length - 1];
+      setCurrentEffect(parentEffect ?? null);
+    }
+  };
+  execute();
+  return () => {
+    isDisposed = true;
+    cleanupEffect(execute);
+    if (typeof cleanup === "function") {
+      cleanup();
+      cleanup = void 0;
+    }
+  };
+}
+
+// src/state/store.ts
+function createStateStore(definitions) {
+  const signals = /* @__PURE__ */ new Map();
+  for (const [name, def] of Object.entries(definitions)) {
+    signals.set(name, createSignal(def.initial));
+  }
+  return {
+    get(name) {
+      const signal = signals.get(name);
+      if (!signal) {
+        throw new Error(`State field "${name}" does not exist`);
+      }
+      return signal.get();
+    },
+    set(name, value) {
+      const signal = signals.get(name);
+      if (!signal) {
+        throw new Error(`State field "${name}" does not exist`);
+      }
+      signal.set(value);
+    }
+  };
+}
+
+// src/expression/evaluator.ts
+function evaluate(expr, ctx) {
+  switch (expr.expr) {
+    case "lit":
+      return expr.value;
+    case "state":
+      return ctx.state.get(expr.name);
+    case "var": {
+      let varName = expr.name;
+      let pathParts = [];
+      if (varName.includes(".")) {
+        const parts = varName.split(".");
+        varName = parts[0];
+        pathParts = parts.slice(1);
+      }
+      if (expr.path) {
+        pathParts = pathParts.concat(expr.path.split("."));
+      }
+      const forbiddenKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+      for (const part of pathParts) {
+        if (forbiddenKeys.has(part)) {
+          return void 0;
+        }
+      }
+      let value = ctx.locals[varName];
+      for (const part of pathParts) {
+        if (value == null) break;
+        value = value[part];
+      }
+      return value;
+    }
+    case "bin":
+      return evaluateBinary(expr.op, expr.left, expr.right, ctx);
+    case "not":
+      return !evaluate(expr.operand, ctx);
+    default:
+      throw new Error("Unknown expression type");
+  }
+}
+function evaluateBinary(op, left, right, ctx) {
+  if (op === "&&") {
+    const leftVal2 = evaluate(left, ctx);
+    if (!leftVal2) return leftVal2;
+    return evaluate(right, ctx);
+  }
+  if (op === "||") {
+    const leftVal2 = evaluate(left, ctx);
+    if (leftVal2) return leftVal2;
+    return evaluate(right, ctx);
+  }
+  const leftVal = evaluate(left, ctx);
+  const rightVal = evaluate(right, ctx);
+  switch (op) {
+    // Arithmetic
+    case "+":
+      if (typeof leftVal === "number" && typeof rightVal === "number") {
+        return leftVal + rightVal;
+      }
+      return String(leftVal) + String(rightVal);
+    case "-":
+      return (typeof leftVal === "number" ? leftVal : 0) - (typeof rightVal === "number" ? rightVal : 0);
+    case "*":
+      return (typeof leftVal === "number" ? leftVal : 0) * (typeof rightVal === "number" ? rightVal : 0);
+    case "/": {
+      const dividend = typeof leftVal === "number" ? leftVal : 0;
+      const divisor = typeof rightVal === "number" ? rightVal : 0;
+      if (divisor === 0) {
+        return dividend === 0 ? NaN : dividend > 0 ? Infinity : -Infinity;
+      }
+      return dividend / divisor;
+    }
+    // Comparison (using strict equality)
+    case "==":
+      return leftVal === rightVal;
+    case "!=":
+      return leftVal !== rightVal;
+    case "<":
+      if (typeof leftVal === "number" && typeof rightVal === "number") {
+        return leftVal < rightVal;
+      }
+      return String(leftVal) < String(rightVal);
+    case "<=":
+      if (typeof leftVal === "number" && typeof rightVal === "number") {
+        return leftVal <= rightVal;
+      }
+      return String(leftVal) <= String(rightVal);
+    case ">":
+      if (typeof leftVal === "number" && typeof rightVal === "number") {
+        return leftVal > rightVal;
+      }
+      return String(leftVal) > String(rightVal);
+    case ">=":
+      if (typeof leftVal === "number" && typeof rightVal === "number") {
+        return leftVal >= rightVal;
+      }
+      return String(leftVal) >= String(rightVal);
+    default:
+      throw new Error("Unknown binary operator: " + op);
+  }
+}
+
+// src/action/executor.ts
+async function executeAction(action, ctx) {
+  for (const step of action.steps) {
+    await executeStep(step, ctx);
+  }
+}
+async function executeStep(step, ctx) {
+  switch (step.do) {
+    case "set":
+      await executeSetStep(step.target, step.value, ctx);
+      break;
+    case "update":
+      await executeUpdateStep(step.target, step.operation, step.value, ctx);
+      break;
+    case "fetch":
+      await executeFetchStep(step, ctx);
+      break;
+  }
+}
+async function executeSetStep(target, value, ctx) {
+  const evalCtx = { state: ctx.state, locals: ctx.locals };
+  const newValue = evaluate(value, evalCtx);
+  ctx.state.set(target, newValue);
+}
+async function executeUpdateStep(target, operation, value, ctx) {
+  const evalCtx = { state: ctx.state, locals: ctx.locals };
+  const currentValue = ctx.state.get(target);
+  switch (operation) {
+    case "increment": {
+      const evalResult = value ? evaluate(value, evalCtx) : 1;
+      const amount = typeof evalResult === "number" ? evalResult : 1;
+      const current = typeof currentValue === "number" ? currentValue : 0;
+      ctx.state.set(target, current + amount);
+      break;
+    }
+    case "decrement": {
+      const evalResult = value ? evaluate(value, evalCtx) : 1;
+      const amount = typeof evalResult === "number" ? evalResult : 1;
+      const current = typeof currentValue === "number" ? currentValue : 0;
+      ctx.state.set(target, current - amount);
+      break;
+    }
+    case "push": {
+      const item = value ? evaluate(value, evalCtx) : void 0;
+      const arr = Array.isArray(currentValue) ? currentValue : [];
+      ctx.state.set(target, [...arr, item]);
+      break;
+    }
+    case "pop": {
+      const arr = Array.isArray(currentValue) ? currentValue : [];
+      ctx.state.set(target, arr.slice(0, -1));
+      break;
+    }
+    case "remove": {
+      const removeValue = value ? evaluate(value, evalCtx) : void 0;
+      const arr = Array.isArray(currentValue) ? currentValue : [];
+      if (typeof removeValue === "number") {
+        ctx.state.set(target, arr.filter((_, i) => i !== removeValue));
+      } else {
+        ctx.state.set(target, arr.filter((x) => x !== removeValue));
+      }
+      break;
+    }
+  }
+}
+async function executeFetchStep(step, ctx) {
+  const evalCtx = { state: ctx.state, locals: ctx.locals };
+  const url = evaluate(step.url, evalCtx);
+  const method = step.method ?? "GET";
+  const fetchOptions = {
+    method
+  };
+  if (step.body) {
+    fetchOptions.body = evaluate(step.body, evalCtx);
+  }
+  try {
+    const response = await fetch(url, fetchOptions);
+    if (response.ok) {
+      const data = await response.json();
+      if (step.result) {
+        ctx.locals[step.result] = data;
+      }
+      if (step.onSuccess) {
+        for (const successStep of step.onSuccess) {
+          await executeStep(successStep, ctx);
+        }
+      }
+    } else {
+      if (step.onError) {
+        for (const errorStep of step.onError) {
+          await executeStep(errorStep, ctx);
+        }
+      }
+    }
+  } catch (_error) {
+    if (step.onError) {
+      for (const errorStep of step.onError) {
+        await executeStep(errorStep, ctx);
+      }
+    }
+  }
+}
+
+// src/renderer/index.ts
+function isEventHandler(value) {
+  return typeof value === "object" && value !== null && "event" in value && "action" in value;
+}
+function render(node, ctx) {
+  switch (node.kind) {
+    case "element":
+      return renderElement(node, ctx);
+    case "text":
+      return renderText(node, ctx);
+    case "if":
+      return renderIf(node, ctx);
+    case "each":
+      return renderEach(node, ctx);
+    default:
+      throw new Error("Unknown node kind");
+  }
+}
+function renderElement(node, ctx) {
+  const el = document.createElement(node.tag);
+  if (node.props) {
+    for (const [propName, propValue] of Object.entries(node.props)) {
+      if (isEventHandler(propValue)) {
+        const handler = propValue;
+        const eventName = handler.event;
+        el.addEventListener(eventName, async (event) => {
+          const action = ctx.actions[handler.action];
+          if (action) {
+            let payload = void 0;
+            if (handler.payload) {
+              payload = evaluate(handler.payload, { state: ctx.state, locals: ctx.locals });
+            }
+            const actionCtx = {
+              state: ctx.state,
+              actions: ctx.actions,
+              locals: { ...ctx.locals, payload },
+              eventPayload: payload
+            };
+            await executeAction(action, actionCtx);
+          }
+        });
+      } else {
+        const cleanup = createEffect(() => {
+          const value = evaluate(propValue, { state: ctx.state, locals: ctx.locals });
+          applyProp(el, propName, value);
+        });
+        ctx.cleanups?.push(cleanup);
+      }
+    }
+  }
+  if (node.children) {
+    for (const child of node.children) {
+      const childNode = render(child, ctx);
+      el.appendChild(childNode);
+    }
+  }
+  return el;
+}
+function applyProp(el, propName, value) {
+  if (propName === "className") {
+    el.className = String(value ?? "");
+  } else if (propName === "style" && typeof value === "string") {
+    el.setAttribute("style", value);
+  } else if (propName === "disabled") {
+    if (value) {
+      el.setAttribute("disabled", "disabled");
+      el.disabled = true;
+    } else {
+      el.removeAttribute("disabled");
+      el.disabled = false;
+    }
+  } else if (propName === "value" && el instanceof HTMLInputElement) {
+    el.value = String(value ?? "");
+  } else if (propName.startsWith("data-")) {
+    el.setAttribute(propName, String(value ?? ""));
+  } else {
+    if (value === true) {
+      el.setAttribute(propName, "");
+    } else if (value === false || value === null || value === void 0) {
+      el.removeAttribute(propName);
+    } else {
+      el.setAttribute(propName, String(value));
+    }
+  }
+}
+function renderText(node, ctx) {
+  const textNode = document.createTextNode("");
+  const cleanup = createEffect(() => {
+    const value = evaluate(node.value, { state: ctx.state, locals: ctx.locals });
+    textNode.textContent = formatValue(value);
+  });
+  ctx.cleanups?.push(cleanup);
+  return textNode;
+}
+function formatValue(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function renderIf(node, ctx) {
+  const anchor = document.createComment("if");
+  let currentNode = null;
+  let currentBranch = "none";
+  let branchCleanups = [];
+  const effectCleanup = createEffect(() => {
+    const condition = evaluate(node.condition, { state: ctx.state, locals: ctx.locals });
+    const shouldShowThen = Boolean(condition);
+    const newBranch = shouldShowThen ? "then" : node.else ? "else" : "none";
+    if (newBranch !== currentBranch) {
+      for (const cleanup of branchCleanups) {
+        cleanup();
+      }
+      branchCleanups = [];
+      if (currentNode && currentNode.parentNode) {
+        currentNode.parentNode.removeChild(currentNode);
+      }
+      const localCleanups = [];
+      const branchCtx = { ...ctx, cleanups: localCleanups };
+      if (newBranch === "then") {
+        currentNode = render(node.then, branchCtx);
+        branchCleanups = localCleanups;
+      } else if (newBranch === "else" && node.else) {
+        currentNode = render(node.else, branchCtx);
+        branchCleanups = localCleanups;
+      } else {
+        currentNode = null;
+      }
+      if (currentNode && anchor.parentNode) {
+        anchor.parentNode.insertBefore(currentNode, anchor.nextSibling);
+      }
+      currentBranch = newBranch;
+    }
+  });
+  ctx.cleanups?.push(effectCleanup);
+  ctx.cleanups?.push(() => {
+    for (const cleanup of branchCleanups) {
+      cleanup();
+    }
+  });
+  const fragment = document.createDocumentFragment();
+  fragment.appendChild(anchor);
+  if (currentNode) {
+    fragment.appendChild(currentNode);
+  }
+  return fragment;
+}
+function renderEach(node, ctx) {
+  const anchor = document.createComment("each");
+  let currentNodes = [];
+  let itemCleanups = [];
+  const effectCleanup = createEffect(() => {
+    const items = evaluate(node.items, { state: ctx.state, locals: ctx.locals });
+    for (const cleanup of itemCleanups) {
+      cleanup();
+    }
+    itemCleanups = [];
+    for (const oldNode of currentNodes) {
+      if (oldNode.parentNode) {
+        oldNode.parentNode.removeChild(oldNode);
+      }
+    }
+    currentNodes = [];
+    if (Array.isArray(items)) {
+      items.forEach((item, index) => {
+        const itemLocals = {
+          ...ctx.locals,
+          [node.as]: item
+        };
+        if (node.index) {
+          itemLocals[node.index] = index;
+        }
+        const localCleanups = [];
+        const itemCtx = {
+          ...ctx,
+          locals: itemLocals,
+          cleanups: localCleanups
+        };
+        const itemNode = render(node.body, itemCtx);
+        currentNodes.push(itemNode);
+        itemCleanups.push(...localCleanups);
+        if (anchor.parentNode) {
+          let refNode = anchor.nextSibling;
+          if (currentNodes.length > 1) {
+            const lastExisting = currentNodes[currentNodes.length - 2];
+            if (lastExisting) {
+              refNode = lastExisting.nextSibling;
+            }
+          }
+          anchor.parentNode.insertBefore(itemNode, refNode);
+        }
+      });
+    }
+  });
+  ctx.cleanups?.push(effectCleanup);
+  ctx.cleanups?.push(() => {
+    for (const cleanup of itemCleanups) {
+      cleanup();
+    }
+  });
+  const fragment = document.createDocumentFragment();
+  fragment.appendChild(anchor);
+  for (const n of currentNodes) {
+    fragment.appendChild(n);
+  }
+  return fragment;
+}
+
+// src/app.ts
+function createApp(program, mount) {
+  const state = createStateStore(program.state);
+  let actions;
+  if (program.actions instanceof Map) {
+    actions = {};
+    program.actions.forEach((action, name) => {
+      actions[name] = action;
+    });
+  } else {
+    actions = program.actions;
+  }
+  const cleanups = [];
+  const ctx = {
+    state,
+    actions,
+    locals: {},
+    cleanups
+  };
+  const rootNode = render(program.view, ctx);
+  mount.appendChild(rootNode);
+  let destroyed = false;
+  return {
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+      while (mount.firstChild) {
+        mount.removeChild(mount.firstChild);
+      }
+    },
+    setState(name, value) {
+      if (destroyed) return;
+      state.set(name, value);
+    },
+    getState(name) {
+      return state.get(name);
+    }
+  };
+}
+export {
+  createApp,
+  createEffect,
+  createSignal,
+  createStateStore,
+  evaluate,
+  executeAction,
+  render
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@constela/runtime",
+  "version": "0.1.0",
+  "description": "Runtime DOM renderer for Constela UI framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@constela/core": "0.1.0",
+    "@constela/compiler": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "jsdom": "^24.0.0",
+    "@types/jsdom": "^21.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}