kopular 0.8.0 → 0.10.0

package/LLM.md

@@ -59,21 +59,20 @@ extern class Validators {
 } from "kopular/forms";
 ```
 
-**`extern class` has no `<T>` syntax** — `extern class FormField<T> { ... }` is a parse
-error (`ExternClassDecl` has no `typeParam`, unlike a real `ClassDecl`/`InterfaceDecl`).
-Describe one concrete instantiation per `T` you actually need instead, aliasing the same
-real export with `as` (the same trust-based, per-shape approach `Http`'s typed-JSON gap
-above already uses) — e.g. for a `FormField<string>`:
+`extern class` supports its own `<T>` (kopscript >= 0.5.0), the same rules as a real
+generic class — describe `FormField<T>` generically instead of per concrete type:
 
 ```ks
-extern class StringField {
-  constructor(string initial, (string) => string? validate);
-  state<string> Value;
+extern class FormField<T> {
+  constructor(T initial, (T) => string? validate);
+  state<T> Value;
   state<string?> Error;
   state<bool> Touched;
   void Touch();
   bool Valid();
-} from "kopular/forms" as "FormField";
+} from "kopular/forms";
+
+FormField<string> email = new FormField<string>("", (string v) => Validators.Email(v));
 ```
 
 `Value`/`Error`/`Touched` are declared as bare properties (`state<T> Value;`, no
@@ -125,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`)
 
@@ -174,6 +189,16 @@ nav.Navigate("/about");                          // pushState + immediate re-ren
   `Render()` finishes swapping the matched page into the outlet, so the very first route
   that matches a page nothing has `Mount()`ed yet fires that page's subscribed listener
   while its inherited `Update()` still has no `ParentElement` to `replaceChild` into.
+- **Navigation guards**: `SetGuard(redirectPath, (string) => bool guard)` — `guard` is
+  called with the target path before every navigation (including a direct load/refresh);
+  returning `false` redirects to `redirectPath` (via `pushState`, so the URL updates too —
+  a refresh on the blocked path lands on the redirect again, not back on the rejected
+  page). One guard for the whole `Router`, not per-route — `guard` itself decides which
+  paths it cares about (`if (path == "/admin") { return loggedIn.Value; } return true;`).
+  Defaults to always-allow (a real `(string path) => true` function, not `null` — a
+  nullable *function type* has the same "can't parenthesize for postfix `?`" problem as
+  an array of one) until `SetGuard` is called. `redirectPath` is never itself
+  guard-checked — pick one `guard` always allows.
 - **Every deployment target needs its own SPA/history-fallback config — this is
   unavoidable, not a Kopular gap.** A direct load or refresh at `/about` is a plain HTTP
   request that reaches your host *before* any JS (Router included) has run, so no

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
@@ -159,6 +161,24 @@ with no extra step. No `Subscribe()` needed on it. Deliberately just one dynamic
 per route for now — no multiple params (`/dogs/:id/toys/:toyId`), no wildcards, no query
 string parsing — each a real, separate extension, not an oversight.
 
+**Navigation guards**: protect a route (or any set of routes) behind a check —
+`SetGuard` takes a redirect path plus a single `(string) => bool` checked before every
+navigation, including a direct load/refresh:
+
+```ks
+nav.SetGuard("/login", (string path) => {
+  if (path == "/admin") { return authService.IsLoggedIn.Value; }
+  return true;
+});
+```
+
+One guard for the whole `Router`, not per-route — the guard function itself decides which
+paths it cares about, the same "a function, not a config object" style `Http`/DI already
+use. Defaults to always-allow when `SetGuard` is never called. Redirecting updates the URL
+too (via `pushState`), so refreshing a blocked path lands on the redirect again rather than
+back on the page the guard just rejected — pick a `redirectPath` the guard itself always
+allows, or it loops.
+
 **Deploying a Router-based app needs SPA/history-fallback configured on whatever you
 deploy to — this is true of every client-side router in every framework, not a Kopular
 gap.** A direct load or a refresh at `/about` is a plain HTTP request that reaches your
@@ -395,10 +415,9 @@ Marking `Render()` `virtual` in the `extern` declaration is what lets a real sub
 for a full working example (components, a service, and routing, all consuming Kopular
 this way).
 
-`extern class` has no `<T>` syntax, so a generic export like `FormField<T>` can't be
-described directly this way — see `LLM.md`'s `FormField<T>`/`Validators` section for the
-per-concrete-type workaround (the same trust-based, per-shape approach the "HTTP" section
-above uses for typed JSON).
+`extern class` can carry its own `<T>` (kopscript >= 0.5.0), so a generic export like
+`FormField<T>` describes the same way a real generic class does — see `LLM.md`'s
+`FormField<T>`/`Validators` section for the full example.
 
 ## Testing your own app: `kopular/testing`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.8.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",
@@ -50,7 +50,7 @@
     }
   },
   "devDependencies": {
-    "kopscript": "^0.4.1",
+    "kopscript": "^0.5.0",
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",

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;
   }

package/src/router.js

@@ -8,6 +8,8 @@ export class Router extends Component {
     (this.Pages = []);
     (this.NotFoundPage = notFoundPage);
     (this.Param = "");
+    (this.Guard = (path) => (true));
+    (this.RedirectPath = "");
     window.addEventListener("popstate", (e) => (this.Update()));
   }
 
@@ -16,13 +18,23 @@ export class Router extends Component {
     (this.Pages = [...this.Pages, page]);
   }
 
+  SetGuard(redirectPath, guard) {
+    (this.RedirectPath = redirectPath);
+    (this.Guard = guard);
+  }
+
   Navigate(path) {
     history.pushState("", "", path);
     this.Update();
   }
 
   Match(path) {
-    let pathSegments = path.split("/");
+    let effectivePath = path;
+    if (!this.Guard(path)) {
+      history.pushState("", "", this.RedirectPath);
+      (effectivePath = this.RedirectPath);
+    }
+    let pathSegments = effectivePath.split("/");
     let found = this.NotFoundPage;
     let param = "";
     for (let i = 0; (i < this.Paths.length); (i = (i + 1))) {

package/src/router.ks

@@ -42,11 +42,27 @@ class Router : Component {
   // inherited Update() has no ParentElement to replaceChild into.
   public string Param;
 
+  // Checked before every navigation, including a direct load/refresh — not
+  // just Navigate()/popstate. Deliberately one guard for the whole Router,
+  // not per-route: the guard function itself decides which paths it cares
+  // about (typically `path.StartsWith("/admin")`-style checks), the same
+  // "no config object, just a function" style Http/DI already use, rather
+  // than a parallel array of per-route guards (which also can't be written
+  // as a type anyway — see AddRoute's own comment on array-of-function
+  // types). Defaults to always-allow, not null — a nullable function TYPE
+  // has the same "can't parenthesize for a postfix `?`" problem as an
+  // array of one, so "no guard configured" is a real function that always
+  // returns true, not a null check.
+  private (string) => bool Guard;
+  private string RedirectPath;
+
   constructor(Component notFoundPage) : base() {
     this.Paths = [];
     this.Pages = [];
     this.NotFoundPage = notFoundPage;
     this.Param = "";
+    this.Guard = (string path) => true;
+    this.RedirectPath = "";
     // 'popstate' only fires on browser back/forward (or history.go/back/
     // forward) — never on pushState itself, unlike hashchange firing
     // whenever location.hash is set. Navigate() below calls Update()
@@ -65,13 +81,29 @@ class Router : Component {
     this.Pages = this.Pages.Push(page);
   }
 
+  // `guard` is called with the path being navigated to; returning false
+  // redirects to `redirectPath` instead (updating the URL via pushState, so
+  // a refresh on the blocked path lands on the redirect too, not back on
+  // the page the guard just rejected). `redirectPath` itself is never
+  // guard-checked — pick one the guard always allows, or it'll loop.
+  public void SetGuard(string redirectPath, (string) => bool guard) {
+    this.RedirectPath = redirectPath;
+    this.Guard = guard;
+  }
+
   public void Navigate(string path) {
     history.pushState("", "", path);
     this.Update();
   }
 
   private Component Match(string path) {
-    string[] pathSegments = path.Split("/");
+    string effectivePath = path;
+    if (!this.Guard(path)) {
+      history.pushState("", "", this.RedirectPath);
+      effectivePath = this.RedirectPath;
+    }
+
+    string[] pathSegments = effectivePath.Split("/");
     Component found = this.NotFoundPage;
     string param = "";
     for (number i = 0; i < this.Paths.Length; i = i + 1) {