kopular 0.9.0 → 0.10.0

package/LLM.md

@@ -124,6 +124,22 @@ w.Bump();                // re-render
   reconciliation. Compose independent components into stable slots (see `Router`'s own
   pattern of keeping page instances alive) to avoid this rather than nesting components
   that both re-render.
+- `RenderError(string message)`: `virtual`, called by `Mount()`/`Update()` (via a private
+  `SafeRender()` wrapper) when `Render()` throws, instead of letting the exception
+  propagate uncaught and crash whatever triggered the render (a click handler, a `Router`
+  navigation). The base implementation just `throw`s `message` again — **purely additive,
+  opt-in error recovery**; a `Component` that never overrides `RenderError` behaves
+  exactly as before this existed. Override it to show a fallback UI instead:
+  ```ks
+  protected override Element RenderError(string message) {
+    Element el = document.createElement("div");
+    el.textContent = "Something went wrong: " + message;
+    return el;
+  }
+  ```
+  A later successful `Update()` (e.g. from a "Retry" button in that fallback calling back
+  into the component) renders normally again — there's no separate "broken" state to
+  reset, `SafeRender()` just tries `Render()` again like any other `Update()`.
 
 ## `Router` (`router.ks`)
 

package/README.md

@@ -15,7 +15,9 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 - **`Component`**: a base class with `virtual Render()` (builds a fresh DOM subtree from
   current state) and `Update()` (swaps the old subtree for the new one). No template
   language, no diffing — components build/update the DOM imperatively against plain DOM
-  bindings, the way you'd write careful vanilla-JS UI code.
+  bindings, the way you'd write careful vanilla-JS UI code. An optional `virtual
+  RenderError(message)` renders a fallback instead of a hard crash if `Render()` throws —
+  purely additive; not overriding it keeps today's exact (uncaught) behavior.
 - **Reactive state, no RxJS**: components hold `state<number>`/`state<string>`/... (a
   KopScript language feature — see the [Kop](https://dev.azure.com/koppinator/Koppindependence/_git/Kop)
   repo) and subscribe once, in their constructor, to call `Update()` on change. No

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, structural directives, and HTTP, with no template DSL and no DI container",
   "type": "module",
   "license": "MIT",

package/src/component.js

@@ -5,14 +5,26 @@ export class Component {
     return document.createElement("div");
   }
 
+  RenderError(message) {
+    throw message;
+  }
+
+  SafeRender() {
+    try {
+      return this.Render();
+    } catch (message) {
+      return this.RenderError(message);
+    }
+  }
+
   Mount(parent) {
     (this.ParentElement = parent);
-    (this.Root = this.Render());
+    (this.Root = this.SafeRender());
     parent.appendChild(this.Root);
   }
 
   Update() {
-    let newRoot = this.Render();
+    let newRoot = this.SafeRender();
     this.ParentElement.replaceChild(newRoot, this.Root);
     (this.Root = newRoot);
   }

package/src/component.ks

@@ -21,14 +21,34 @@ class Component {
     return document.createElement("div");
   }
 
+  // Overridden to render a fallback UI when Render() throws — a page bug,
+  // an unhandled rejected Http call, anything — instead of leaving
+  // Mount()/Update() to propagate the exception uncaught, which would
+  // otherwise crash whatever triggered the render (a click handler, a
+  // Router navigation) with nothing shown to the user at all. Default just
+  // re-throws, so anything that doesn't override this keeps today's exact
+  // behavior — this is purely additive, opt-in error recovery, not a
+  // behavior change for existing components.
+  protected virtual Element RenderError(string message) {
+    throw message;
+  }
+
+  private Element SafeRender() {
+    try {
+      return this.Render();
+    } catch (string message) {
+      return this.RenderError(message);
+    }
+  }
+
   public void Mount(Element parent) {
     this.ParentElement = parent;
-    this.Root = this.Render();
+    this.Root = this.SafeRender();
     parent.appendChild(this.Root);
   }
 
   protected void Update() {
-    Element newRoot = this.Render();
+    Element newRoot = this.SafeRender();
     this.ParentElement.replaceChild(newRoot, this.Root);
     this.Root = newRoot;
   }