kopular 1.1.3 → 1.1.5

package/GUIDE.md

@@ -34,6 +34,23 @@ both scripts). `ks check src/app.ks` type-checks without building, if you just w
   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).
+- **Comments are `//` only** — there is no `/* ... */` block comment, and a `/*` is a parse
+  error (`KS2020`), not an ignored region.
+- **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
@@ -42,6 +59,9 @@ both scripts). `ks check src/app.ks` type-checks without building, if you just w
   `.Split(sep)`, `.Replace(from, to)`, `.CompareTo(other)` (sort comparator), `+` concatenates.
   Both `"double"` and `'single'` quotes work — use whichever the other isn't, e.g. inside
   a template attribute (`*if="Name != ''"`).
+- Arrays are created with a literal and nothing else: `number[] xs = [];`, `[1, 2, 3]`,
+  `[new Todo("a")]`. **There is no `new number[3]` form** — that's a parse error, not an
+  empty array.
 - Arrays: `xs.Length`, `.Map()/.Filter()/.ForEach()/.Find()/.FindIndex()/.Includes()/.IndexOf()`,
   `.Sort(cmp)/.Reverse()/.Push(x)` (all three **non-mutating**, return a new array),
   `.Slice(a, b)/.Concat(ys)/.Join(sep)/.Reduce(fn, initial)`.
@@ -126,6 +146,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.
 
@@ -166,7 +192,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");
@@ -176,8 +202,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.
@@ -203,8 +233,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>`
 
@@ -217,6 +278,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),
@@ -228,6 +291,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";
 }
@@ -268,6 +332,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/LLM.md

@@ -171,7 +171,7 @@ extern class Router {
   // is in flight — default: `<div class="router-loading">Loading...</div>`.
   // Only declare this if you actually override it (a class extending
   // Router) — see "Lazy routes" below.
-  protected virtual VElement BuildLoadingPlaceholder();
+  virtual VElement BuildLoadingPlaceholder();
   void Navigate(string path);
   void Mount(Element parent);
   // One guard for the whole Router, not per-route — see "Router" below.
@@ -320,6 +320,7 @@ w.Bump();                // re-render + diff + patch
   component, applied once the handler returns:
   ```ks
   private void Save() {
+    Item newItem = new Item(this.Draft);      // whatever this handler just built
     this.Draft = "";                          // a plain field Render() also reads
     this.Items.Value = this.Items.Value.Push(newItem);  // triggers the ONE render, via Subscribe
   }
@@ -503,7 +504,7 @@ Real URLs via the History API (`pushState`/`popstate`), not hash routing.
 
 ```ks
 class NotFoundPage : Component {
-  public override VElement Render() { /* ... */ }
+  public override VElement Render() { return VElement.Create("h1"); }
 }
 class HomePage : Component {
   private Router Nav;

package/README.md

@@ -641,7 +641,7 @@ own `header.ks`/`nav.ks` use it exactly this way):
 ```ks
 VElement header = VElement.Create("header");
 header.RawHtml = SiteHeaderHtml; // a raw string ... from "./header.html"; constant
-header.OnClick = (Event e) => { /* one delegated listener over the whole subtree */ };
+header.OnClick = (Event e) => { };  // one delegated listener over the whole subtree
 ```
 
 **It's unescaped, real `innerHTML` — never assign it anything reachable from user input.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "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",