kopular 0.8.0 → 0.9.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
@@ -174,6 +173,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

@@ -159,6 +159,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 +413,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.9.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/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) {