kopular 1.1.2 → 1.1.4

package/GUIDE.md

@@ -27,9 +27,28 @@ both scripts). `ks check src/app.ks` type-checks without building, if you just w
 - No implicit `this` — every member reference is `this.Field`/`this.Method()`, always,
   including inside a lambda.
 - `if`/`else`/`while`/`for`/`foreach (Type x in xs)` — all statements, no ternary. Use
-  `match` for a conditional value: `match x { 1 => "one", _ => "other" }` (the `_` arm is
-  required unless every case is covered, e.g. an enum).
+  `match` for a conditional value: `match x { "a" => "one", _ => "other" }`. **The subject
+  must be `string` or an `enum` — never `bool`/`number`/anything else, and every pattern
+  must be a string literal (or, for an enum subject, an `Enum.Member` name) — not a number,
+  not `true`/`false`.** The `_` arm is required unless every case is covered (only possible
+  for an enum subject, by naming every member). For a `bool`, use `if`/`else` instead —
+  there's no equivalent shorthand.
 - Lambdas need explicit parameter types: `(number x) => x * 2`.
+- Operators: `+ - * / %`, `== != < > <= >=`, `&& || !` — `!` is a real unary operator on a
+  `bool` (`if (!done)`, `bool flipped = !done;`). Precedence, low → high: `=` → `||` →
+  `&&` → `==` `!=` → `<` `>` `<=` `>=` → `+` `-` → `*` `/` `%` → unary `-` `!` →
+  `.member`/`(call)`/`[index]`. **No `++`/`--`/`+=`** — write `i = i + 1;`.
+- **number → string**: `+` with a string on either side (`"count: " + n`), or interpolation
+  (`$"{n} items left"`). There is no `.ToString()` — calling it is `KS4085`.
+- `try { } catch (string e) { } finally { }` and `throw "message";` all exist — one `catch`
+  per `try`, and its parameter type is your choice (it is *not* checked against what was
+  actually thrown).
+- **Reserved words**: naming a local or parameter one of these is a parse error, not
+  shadowing — `raw`, `state`, `task`, `from`, `as`, `get`, `set`, `in`, `base` and `match`
+  are the ones easy to pick by accident. Full list: `using extern raw template styles from
+  as const class interface enum constructor public private protected static virtual override
+  get set return if else while for foreach in break continue match this base new void true
+  false null task state async await try catch finally throw`.
 - Nullable: `string? name` — a nullable field forces `if (x != null) { ... }` before use;
   narrowing is scoped to that `if` block, not reachability-based (an early
   `if (x == null) { return; }` does NOT narrow `x` afterward — wrap the rest in
@@ -122,6 +141,12 @@ public override VElement Render() {
 escape hatch for anything without a named field). Both styles compile to the same thing and
 mix freely across a project.
 
+**Conditional value**: there's no ternary, so to pick between two elements use `If()` (from
+`kopular/directives`, already covered by `using "kopular"`):
+```ks
+root.AppendChild(If(this.On.Value, () => this.Yes(), () => this.No()));
+```
+
 **Error boundary**: override `RenderError(string message)` to show a fallback instead of an
 uncaught crash if `Render()` throws.
 
@@ -162,7 +187,7 @@ Router nav = new Router(new NotFoundPage());  // fallback page, required
 nav.AddRoute("/", new HomePage(nav));
 nav.AddRoute("/dogs/:id", new DogDetailPage(nav));  // nav.Param inside that page
 nav.SetGuard("/login", (string path) => {
-  if (path == "/admin") { return authService.LoggedIn; }
+  if (path == "/admin") { return auth.LoggedIn.Value; }  // .Value — a state<bool> is not a bool
   return true;
 });
 nav.Navigate("/dogs/1");
@@ -172,8 +197,12 @@ nav.Mount(document.body);
   navigating away and back.
 - `nav.Param` — the first `:name` segment, a plain `string` (not `state<T>`; the outlet
   re-renders on every navigation already).
-- `SetGuard(redirectPath, guard)`: one guard for the whole router; `guard` returns `false`
-  to redirect. Defaults to always-allow.
+- `SetGuard(redirectPath, guard)`: one guard for the whole router, called with the target
+  path before **every** navigation — in-app, a direct load/refresh, and back/forward alike,
+  so a guarded page is covered however it's reached. Returning `false` redirects to
+  `redirectPath` (via `pushState`, so the URL changes too). `guard` itself decides which
+  paths it cares about, and `redirectPath` is never guard-checked, so pick one the guard
+  always allows. Defaults to always-allow.
 - `AddLazyRoute(path, loader)` for real code-splitting — see "Lazy routes" below.
 - Every deploy target needs its own SPA fallback (serve `index.html` for any route with no
   matching file) — a plain HTTP limitation, not a Kopular one.
@@ -199,8 +228,39 @@ Response r = await Http.Get("/api/dogs");
 if (r.ok) { string body = await r.text(); }
 await Http.Post("/api/dogs", "{\"name\":\"Rex\"}");
 ```
-No typed JSON deserialization built in — describe the shape as `extern class` and parse
-with `extern MyShape Parse(string json) as "JSON.parse";`.
+No typed JSON deserialization built in — describe the shape as an `extern class` and bind
+`JSON.parse`. Note the `;` after an `extern class` body, and never write `async` on an
+`extern` signature (give it a `task<T>` return type instead):
+
+```ks
+extern class User {
+  number id { get; }
+  string name { get; }
+  string email { get; }
+};
+extern User[] ParseUsers(string json) as "JSON.parse";
+```
+
+A complete load-with-states method. `async` methods return `task` or `task<T>`, never a
+bare value type:
+
+```ks
+public async task Load() {
+  this.Status.Value = "loading";
+  try {
+    Response r = await Http.Get("/api/users");
+    if (r.ok) {
+      string body = await r.text();
+      this.Users.Value = ParseUsers(body);
+      this.Status.Value = "ok";
+    } else {
+      this.Status.Value = "error";
+    }
+  } catch (string e) {
+    this.Status.Value = "error";
+  }
+}
+```
 
 ## Async: `Delay`, `Computed`, `Resource<T>`
 
@@ -213,6 +273,8 @@ Computed2<number, number, number> total = new Computed2<number, number, number>(
 total.Value.Subscribe((number v) => this.Update());  // total.Value is itself state<number>
 
 Resource<Response> r = new Resource<Response>(Http.Get(url));  // task already in flight
+// Data is state<T?> and Error is state<string?> — both null until the task settles, so
+// whatever these arms call has to accept the nullable type (or null-check first).
 match r.Status.Value {
   AsyncStatus.Loading => BuildSpinner(),
   AsyncStatus.Success => BuildContent(r.Data.Value),
@@ -224,6 +286,7 @@ match r.Status.Value {
 
 ```ks
 class Widget : Component {
+  constructor() : base() { }   // required: 'styles from' has to have one to initialize from
   template from "./widget.html";
   styles from "./widget.css";
 }
@@ -264,6 +327,8 @@ Real jsdom, real compile, real DOM assertions — not a mock.
 
 - Forgetting `this.` on a member reference inside a lambda — it's a real undefined-identifier
   error, not automatic.
+- A `state<T>` used where a plain `T` is expected needs `.Value` — including a `bool` one
+  returned from a router guard or passed to `If()` (`KS4038`).
 - `if (x == null) { return; } use(x);` does NOT narrow `x` — see "Nullable" above.
 - A two-way binding target must be a field path (`Field`, `this.Field`, `Field.Value`), never
   a method call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, real compiled templates, and HTTP, with no DI container",
   "type": "module",
   "license": "MIT",