@constela/runtime 0.4.0 → 0.7.0

package/dist/index.d.ts

@@ -26,6 +26,7 @@ declare function createEffect(fn: EffectFn): () => void;
 interface StateStore {
     get(name: string): unknown;
     set(name: string, value: unknown): void;
+    subscribe(name: string, fn: (value: unknown) => void): () => void;
 }
 interface StateDefinition {
     type: string;
@@ -100,4 +101,28 @@ interface AppInstance {
 }
 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 };
+/**
+ * Hydrate - Attach to existing SSR-rendered HTML
+ *
+ * This module provides client-side hydration for server-rendered Constela apps.
+ * It attaches event handlers and enables reactivity without reconstructing the DOM.
+ */
+
+/**
+ * Options for hydrating an SSR-rendered application
+ */
+interface HydrateOptions {
+    /** The compiled program to hydrate */
+    program: CompiledProgram;
+    /** The container element containing SSR-rendered HTML */
+    container: HTMLElement;
+}
+/**
+ * Hydrates a server-rendered application.
+ *
+ * @param options - Hydration options containing program and container
+ * @returns AppInstance for controlling the hydrated application
+ */
+declare function hydrateApp(options: HydrateOptions): AppInstance;
+
+export { type ActionContext, type AppInstance, type EvaluationContext, type HydrateOptions, type RenderContext, type Signal, type StateStore, createApp, createEffect, createSignal, createStateStore, evaluate, executeAction, hydrateApp, render };

package/dist/index.js

@@ -111,6 +111,13 @@ function createStateStore(definitions) {
         throw new Error(`State field "${name}" does not exist`);
       }
       signal.set(value);
+    },
+    subscribe(name, fn) {
+      const signal = signals.get(name);
+      if (!signal) {
+        throw new Error(`State field "${name}" does not exist`);
+      }
+      return signal.subscribe(fn);
     }
   };
 }
@@ -732,6 +739,410 @@ function createApp(program, mount) {
     }
   };
 }
+
+// src/hydrate.ts
+function isEventHandler2(value) {
+  return typeof value === "object" && value !== null && "event" in value && "action" in value;
+}
+function hydrateApp(options) {
+  const { program, container } = options;
+  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 firstChild = container.firstElementChild;
+  if (firstChild) {
+    hydrate(program.view, firstChild, ctx);
+  }
+  let destroyed = false;
+  return {
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+      while (container.firstChild) {
+        container.removeChild(container.firstChild);
+      }
+    },
+    setState(name, value) {
+      if (destroyed) return;
+      state.set(name, value);
+    },
+    getState(name) {
+      return state.get(name);
+    }
+  };
+}
+function hydrate(node, domNode, ctx) {
+  switch (node.kind) {
+    case "element":
+      hydrateElement(node, domNode, ctx);
+      break;
+    case "text":
+      hydrateText(node, domNode, ctx);
+      break;
+    case "if":
+      hydrateIf(node, domNode, ctx);
+      break;
+    case "each":
+      hydrateEach(node, domNode, ctx);
+      break;
+    case "markdown":
+    case "code":
+      break;
+    default:
+      break;
+  }
+}
+function hydrateElement(node, el, ctx) {
+  if (node.props) {
+    for (const [propName, propValue] of Object.entries(node.props)) {
+      if (isEventHandler2(propValue)) {
+        const handler = propValue;
+        const eventName = handler.event;
+        el.addEventListener(eventName, async (event) => {
+          const action = ctx.actions[handler.action];
+          if (action) {
+            const eventLocals = {};
+            const target = event.target;
+            if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
+              eventLocals["value"] = target.value;
+              if (target instanceof HTMLInputElement && target.type === "checkbox") {
+                eventLocals["checked"] = target.checked;
+              }
+            }
+            let payload = void 0;
+            if (handler.payload) {
+              payload = evaluate(handler.payload, {
+                state: ctx.state,
+                locals: { ...ctx.locals, ...eventLocals }
+              });
+            }
+            const actionCtx = {
+              state: ctx.state,
+              actions: ctx.actions,
+              locals: { ...ctx.locals, ...eventLocals, payload },
+              eventPayload: payload
+            };
+            await executeAction(action, actionCtx);
+          }
+        });
+      } else {
+        const cleanup = createEffect(() => {
+          const value = evaluate(propValue, {
+            state: ctx.state,
+            locals: ctx.locals
+          });
+          applyProp2(el, propName, value);
+        });
+        ctx.cleanups.push(cleanup);
+      }
+    }
+  }
+  if (node.children) {
+    hydrateChildren(node.children, el, ctx);
+  }
+}
+function hydrateChildren(children, parent, ctx) {
+  const domChildren = [];
+  for (let i = 0; i < parent.childNodes.length; i++) {
+    const child = parent.childNodes[i];
+    if (child.nodeType !== Node.COMMENT_NODE) {
+      domChildren.push(child);
+    }
+  }
+  let domIndex = 0;
+  for (let i = 0; i < children.length; i++) {
+    const childNode = children[i];
+    if (childNode.kind === "text") {
+      const textNodes = [childNode];
+      while (i + 1 < children.length && children[i + 1].kind === "text") {
+        i++;
+        textNodes.push(children[i]);
+      }
+      const domChild = domChildren[domIndex];
+      if (domChild && domChild.nodeType === Node.TEXT_NODE) {
+        hydrateTextGroup(textNodes, domChild, ctx);
+        domIndex++;
+      }
+    } else if (childNode.kind === "element") {
+      const domChild = domChildren[domIndex];
+      if (domChild && domChild.nodeType === Node.ELEMENT_NODE) {
+        hydrate(childNode, domChild, ctx);
+        domIndex++;
+      }
+    } else if (childNode.kind === "if") {
+      const domChild = domChildren[domIndex];
+      if (domChild) {
+        hydrate(childNode, domChild, ctx);
+        domIndex++;
+      }
+    } else if (childNode.kind === "each") {
+      const items = evaluate(childNode.items, {
+        state: ctx.state,
+        locals: ctx.locals
+      });
+      const itemCount = Array.isArray(items) ? items.length : 0;
+      if (itemCount > 0) {
+        const firstDomChild = domChildren[domIndex];
+        if (firstDomChild) {
+          hydrate(childNode, firstDomChild, ctx);
+          domIndex += itemCount;
+        }
+      }
+    } else {
+      const domChild = domChildren[domIndex];
+      if (domChild) {
+        hydrate(childNode, domChild, ctx);
+        domIndex++;
+      }
+    }
+  }
+}
+function hydrateTextGroup(nodes, textNode, ctx) {
+  const cleanup = createEffect(() => {
+    let combinedText = "";
+    for (const node of nodes) {
+      const value = evaluate(node.value, {
+        state: ctx.state,
+        locals: ctx.locals
+      });
+      combinedText += formatValue2(value);
+    }
+    textNode.textContent = combinedText;
+  });
+  ctx.cleanups.push(cleanup);
+}
+function applyProp2(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 hydrateText(node, textNode, ctx) {
+  const cleanup = createEffect(() => {
+    const value = evaluate(node.value, {
+      state: ctx.state,
+      locals: ctx.locals
+    });
+    textNode.textContent = formatValue2(value);
+  });
+  ctx.cleanups.push(cleanup);
+}
+function formatValue2(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function hydrateIf(node, initialDomNode, ctx) {
+  const anchor = document.createComment("if");
+  const parent = initialDomNode.parentNode;
+  if (!parent) return;
+  parent.insertBefore(anchor, initialDomNode);
+  let currentNode = initialDomNode;
+  let currentBranch = "none";
+  let branchCleanups = [];
+  let isFirstRun = true;
+  const initialCondition = evaluate(node.condition, {
+    state: ctx.state,
+    locals: ctx.locals
+  });
+  currentBranch = Boolean(initialCondition) ? "then" : node.else ? "else" : "none";
+  if (currentBranch === "then") {
+    const localCleanups = [];
+    const branchCtx = { ...ctx, cleanups: localCleanups };
+    hydrate(node.then, currentNode, branchCtx);
+    branchCleanups = localCleanups;
+  } else if (currentBranch === "else" && node.else) {
+    const localCleanups = [];
+    const branchCtx = { ...ctx, cleanups: localCleanups };
+    hydrate(node.else, currentNode, branchCtx);
+    branchCleanups = localCleanups;
+  }
+  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 (isFirstRun) {
+      isFirstRun = false;
+      return;
+    }
+    if (newBranch !== currentBranch) {
+      for (const cleanup of branchCleanups) {
+        cleanup();
+      }
+      branchCleanups = [];
+      if (currentNode && currentNode.parentNode) {
+        currentNode.parentNode.removeChild(currentNode);
+      }
+      const localCleanups = [];
+      const branchCtx = {
+        state: ctx.state,
+        actions: ctx.actions,
+        locals: ctx.locals,
+        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();
+    }
+  });
+}
+function hydrateEach(node, firstItemDomNode, ctx) {
+  const parent = firstItemDomNode.parentNode;
+  if (!parent) return;
+  const anchor = document.createComment("each");
+  parent.insertBefore(anchor, firstItemDomNode);
+  let currentNodes = [];
+  let itemCleanups = [];
+  const initialItems = evaluate(node.items, {
+    state: ctx.state,
+    locals: ctx.locals
+  });
+  let isFirstRun = true;
+  if (Array.isArray(initialItems) && initialItems.length > 0) {
+    let domNode = firstItemDomNode;
+    initialItems.forEach((item, index) => {
+      if (!domNode) return;
+      currentNodes.push(domNode);
+      const itemLocals = {
+        ...ctx.locals,
+        [node.as]: item
+      };
+      if (node.index) {
+        itemLocals[node.index] = index;
+      }
+      const localCleanups = [];
+      const itemCtx = {
+        ...ctx,
+        locals: itemLocals,
+        cleanups: localCleanups
+      };
+      hydrate(node.body, domNode, itemCtx);
+      itemCleanups.push(...localCleanups);
+      domNode = domNode.nextSibling;
+      while (domNode && domNode.nodeType === Node.COMMENT_NODE) {
+        domNode = domNode.nextSibling;
+      }
+    });
+  }
+  const effectCleanup = createEffect(() => {
+    const items = evaluate(node.items, {
+      state: ctx.state,
+      locals: ctx.locals
+    });
+    if (isFirstRun) {
+      isFirstRun = false;
+      return;
+    }
+    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 = {
+          state: ctx.state,
+          actions: ctx.actions,
+          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();
+    }
+  });
+}
 export {
   createApp,
   createEffect,
@@ -739,5 +1150,6 @@ export {
   createStateStore,
   evaluate,
   executeAction,
+  hydrateApp,
   render
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/runtime",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Runtime DOM renderer for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,8 @@
     "jsdom": "^24.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
-    "vitest": "^2.0.0"
+    "vitest": "^2.0.0",
+    "@constela/server": "0.1.2"
   },
   "engines": {
     "node": ">=20.0.0"