kopular 1.2.3 → 1.2.5

package/GUIDE.md

@@ -1,13 +1,14 @@
 # Kopular quick guide
 
-Everything for typical app work. For what isn't here — generics, nullable depth, advanced
-routing, the diagnostic list — see this package's `LLM.md` and `node_modules/kopscript/LLM.md`.
+Everything you need for typical app work, in one page. For anything not covered here —
+generics, nullable types, advanced routing, the full diagnostic list — see this package's
+own `LLM.md` and `node_modules/kopscript/LLM.md`.
 
 ## Setup
 
-Every file starts with `using "kopular";` (the DOM and every Kopular type), plus
-`using "./other_file";` per project file it references. `using` isn't transitive: list every
-file you use, not just your dependencies' dependencies.
+Every file starts with `using "kopular";` for the DOM and every Kopular type, plus
+`using "./other_file";` per project file it needs (`using` isn't transitive — list every
+file you reference, not just direct dependencies' dependencies).
 
 ```ks
 using "kopular";
@@ -17,51 +18,71 @@ Counter app = new Counter();
 app.Mount(document.body);
 ```
 
-`npm start` builds and serves; `ks check src/app.ks` type-checks without building.
+Run `npm run build && npm run serve`, or `npm start` (a scaffolded project already has
+both scripts). `ks check src/app.ks` type-checks without building, if you just want errors.
 
 ## The language you need
 
-- `Type name = value;` for every local — no `let`/`var`, no inference.
-- **No implicit `this`** — always `this.Field`/`this.Method()`, lambdas included.
-- `if`/`else`/`while`/`for`/`foreach (Type x in xs)` are statements, and there is no ternary.
-  For a conditional *value* use `match`: `match x { "a" => "one", _ => "other" }`. **The
-  subject must be `string` or an `enum`** — never `bool`/`number` — and every pattern must be
-  a string literal or an `Enum.Member` name. `_` is required unless an enum subject names
-  every member. For a `bool`, use `if`/`else`.
+- `Type name = value;` for every local — no `let`/`var`, no inference on declarations.
+- 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 { "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)`). Precedence is conventional: `||` below `&&` below comparisons below
-  `+ -` below `* / %` below unary. **No `++`/`--`/`+=`** — write `i = i + 1;`.
-- **number → string**: `"count: " + n`, or `$"{n} items left"`. No `.ToString()` (`KS4085`).
+- 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`, its parameter type your choice and unchecked against what was thrown.
-- **Comments are `//` only** — `/* ... */` is a parse error (`KS2020`), not an ignored region.
-- **Reserved words** as a local/parameter name are a parse error, not shadowing. Easy to pick
-  by accident: `raw`, `state`, `task`, `from`, `as`, `get`, `set`, `in`, `base`, `match`.
-- Nullable `string? name` forces `if (x != null) { ... }` before use. Narrowing is scoped to
-  that block, not reachability-based: an early `if (x == null) { return; }` does **not**
-  narrow afterwards — wrap the rest in `if (x != null) { ... }`.
-- `x == null`/`x != null` also match `undefined` — a missed `.Find()`, an absent optional field.
-- Strings: `.Length`, `.Contains()/.StartsWith()/.EndsWith()`, `.Trim()/.ToUpper()/.ToLower()`,
-  `.Split(sep)`, `.Replace(from, to)`, `.CompareTo(other)` (a sort comparator), `+` concatenates.
-  `"double"` and `'single'` quotes both work — use whichever the surrounding context isn't,
-  e.g. `*if="Name != ''"` inside a template attribute.
-- **Arrays are created by literal only**: `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: `.Length`, `.Map()/.Filter()/.ForEach()/.Find()/.FindIndex()/.Includes()/.IndexOf()`,
-  `.Sort(cmp)/.Reverse()/.Push(x)` (**all three non-mutating** — each returns a new array),
+  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
+  `if (x != null) { ... }` instead).
+- Strings: `s.Length`, `.Contains()/.StartsWith()/.EndsWith()`, `.Trim()/.ToUpper()/.ToLower()`,
+  `.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)`.
-- **No `.Match()`/`.Test()`/`.Exec()` on `string`** — there is no regex-execute at all. A regex
-  literal (`r"^[a-z]+$"`) only means something as a `match` *pattern*. To classify by character
-  class, `.Split("")` into single characters and `match` each one:
+- `x == null` / `x != null` also match `undefined` — a missed `Array.Find`, an absent
+  optional field, etc. all read as `null`.
+- **No `.Match()`/`.Test()`/`.Exec()` on `string` — there is no direct regex-execute method
+  at all.** A regex literal (`r"^[a-z]+$"`) only means something as a `match` *pattern*.
+  The idiomatic way to classify or extract by character class is `.Split("")` (splits into
+  a `string[]` of single characters) plus `match` per character:
   ```ks
   bool isLetter = match c { r"^[a-z]$" => true, _ => false };
   ```
-  Build words/tokens by appending matching characters to an accumulator and flushing it on a
-  non-match or at the end. Reach for a hand-written `.js` shim only for what a pattern genuinely
-  can't express, like capturing a submatch.
-- **No object-literal syntax** — `{ key: value }` isn't a value anywhere. A JS API needing one
-  wants a small `.js` shim; `Http`/`FormField` already cover the common cases.
+  Build up runs (words, tokens, ...) by iterating those characters and appending to an
+  accumulator string, flushing it whenever a non-matching character (or the end) is
+  reached — this covers tokenizing/extracting by character class without ever needing a
+  hand-written JS shim. Reach for a real shim (below) only for something a `match` pattern
+  genuinely can't express, like capturing a submatch.
+- No object-literal syntax anywhere (`{ key: value }` doesn't exist as a value). A JS API
+  that needs one (rare — `fetch`'s options, `addEventListener`'s options object) needs a
+  small hand-written `.js` shim; Kopular's own `Http`/`FormField` cover the common cases so
+  you'll rarely hit this.
 
 ## Components
 
@@ -77,20 +98,21 @@ class Counter : Component {
 <button (click)="Increment()">Count: {{ Count.Value }}</button>
 ```
 
-A `state<T>` referenced directly in a template auto-subscribes. State reached *indirectly*
-(through a method, or `this.SomeService.Count`) needs one in the constructor:
-`this.SomeService.Count.Subscribe((v) => this.Update());`
+`state<T>` referenced directly in a template auto-subscribes — no manual `Subscribe`
+needed. State reached *indirectly* (through a method, or `this.SomeService.Count`) does
+need one: `this.SomeService.Count.Subscribe((v) => this.Update());` in the constructor.
 
 **Template bindings**: `{{ expr }}` text, `[prop]="expr"` (real fields for
-`id`/`className`/`value`/`disabled`/`checked`; anything else becomes a plain attribute),
-`(click)`/`(input)`/`(blur)`/`(change)` events, `*if="expr"`, `*for="Type v of expr"` (element
-type required, never inferred), `*mount="expr"` (embeds a live child component, composes with
-`*for`).
-
-**Two-way binding, `[(value)]="Field"`** — `Field` may be a bare name, `this.Field`, or a member
-path, and is assigned back directly, so it must resolve to something assignable, never a method
-call. **A `state<T>` field needs `.Value`** — `[(value)]="Qty.Value"`, since a bare `state<T>`
-isn't a `string`:
+`id`/`className`/`value`/`disabled`/`checked`; anything else is a plain attribute),
+`(click)`/`(input)`/`(blur)`/`(change)` events, `*if="expr"`, `*for="Type v of expr"`
+(element type required, no inference), `*mount="expr"` (embeds a live child component,
+composes with `*for`).
+
+**Two-way binding, `[(value)]="Field"`** — `Field` can be a bare name, `this.Field`, or a
+member path; it's assigned back directly (`Field = e.target.value`), so it must resolve
+to something assignable, never a method call. **A `state<T>` field needs `.Value` on the
+end** — `[(value)]="Qty.Value"`, not `[(value)]="Qty"` (a bare `state<T>` isn't itself a
+`string`, so binding it directly is a type error):
 ```ks
 public state<string> Qty;
 constructor() : base() { this.Qty = state("1"); }
@@ -99,8 +121,8 @@ constructor() : base() { this.Qty = state("1"); }
 <input [(value)]="Qty.Value" />
 ```
 
-**Exactly one top-level element per template** — no auto-wrapping, a hard compile error
-otherwise. Wrap multiple pieces in one container:
+**Exactly one top-level element per template — no auto-wrapping, a hard compile error
+otherwise.** Wrap multiple top-level pieces in one real container element:
 ```html
 <div>
   <input id="text" [(value)]="Draft" />
@@ -108,7 +130,8 @@ otherwise. Wrap multiple pieces in one container:
 </div>
 ```
 
-**Hand-written `Render()`**, for logic too dynamic for a template:
+**Hand-written `Render()`** (needed when logic is too dynamic for a template, or a template
+would obscure more than it clarifies):
 
 ```ks
 public override VElement Render() {
@@ -119,17 +142,18 @@ public override VElement Render() {
 }
 ```
 `VElement.Create(tag)`, `.TextContent/.ClassName/.Id/.Value/.RawHtml/.Disabled/.Checked`,
-`.OnClick/.OnInput/.OnBlur/.OnChange`, `.AppendChild(child)`, `.SetAttr(name, value)` (the escape
-hatch for anything without a named field). Both styles compile to the same thing and mix freely.
+`.OnClick/.OnInput/.OnBlur/.OnChange`, `.AppendChild(child)`, `.SetAttr(name, value)` (the
+escape hatch for anything without a named field). Both styles compile to the same thing and
+mix freely across a project.
 
-**Conditional value**: no ternary, so to pick between two elements use `If()` (from
+**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)` for a fallback instead of an uncaught
-crash when `Render()` throws.
+**Error boundary**: override `RenderError(string message)` to show a fallback instead of an
+uncaught crash if `Render()` throws.
 
 ## Nested components & content projection
 
@@ -140,15 +164,15 @@ this.Items.ForEach((Item item) => {
   list.AppendChild(slot);
 });
 ```
-A template does the same with `<li *for="Item i of Items" *mount="i"></li>`.
+A template does the same via `<li *for="Item i of Items" *mount="i"></li>`.
 
-Content projection (React's `children`): pass a `() => VElement` into a constructor and call it
-from `Render()`.
+Content projection (React's `children`): pass a `() => VElement` into a constructor, call
+it from `Render()` — no separate mechanism needed.
 
 ## Services — no DI container
 
-A service is a plain class; "injecting" it is a constructor argument. Wire it once in a
-composition root:
+A service is a plain class; "injecting" it is a constructor argument. Wire everything once
+in a composition root:
 
 ```ks
 class AppContainer {
@@ -174,16 +198,19 @@ nav.SetGuard("/login", (string path) => {
 nav.Navigate("/dogs/1");
 nav.Mount(document.body);
 ```
-- Routes hold already-built `Component`s, not factories — state survives navigating away and back.
-- `nav.Param` — the first `:name` segment, a plain `string` (not `state<T>`; the outlet re-renders
-  on every navigation anyway).
-- `SetGuard(redirectPath, guard)`: one guard for the whole router, called with the target path
-  before **every** navigation — in-app, direct load/refresh, and back/forward alike. Returning
-  `false` redirects to `redirectPath` via `pushState`. The guard decides which paths it cares
-  about; `redirectPath` is never itself guard-checked, so pick one the guard always allows.
-- `AddLazyRoute(path, loader)` for code-splitting — see below.
+- Routes hold already-built `Component`s, not factories — built once, state survives
+  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, 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). That's an HTTP limitation, not a Kopular one.
+  matching file) — a plain HTTP limitation, not a Kopular one.
 
 ## Forms
 
@@ -196,9 +223,8 @@ FormField<string> email = new FormField<string>("", (string v) => {
 email.Value.Value = "not-an-email";
 print(email.Error.Value);  // "Must be a valid email"
 ```
-`Validators`: `Required/MinLength/MaxLength/Email/Min/Max`, each returning a message or `null`.
-There's no array-of-validators parameter — chain checks in one lambda, as above, or use
-`CombineValidators2`/`CombineValidators3`.
+`Validators`: `Required/MinLength/MaxLength/Email/Min/Max`, each returns an error message
+or `null`. No array-of-validators param — chain checks in one lambda, as above.
 
 ## HTTP
 
@@ -207,9 +233,9 @@ 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 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:
+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 {
@@ -220,8 +246,8 @@ extern class User {
 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:
+A complete load-with-states method. `async` methods return `task` or `task<T>`, never a
+bare value type:
 
 ```ks
 public async task Load() {
@@ -270,8 +296,8 @@ class Widget : Component {
   styles from "./widget.css";
 }
 ```
-Every selector in `widget.css` is rewritten to match only this class's own elements. The class
-must have a constructor.
+Every selector in `widget.css` is rewritten to only match this class's own elements —
+never a sibling's or child's. Needs a constructor to exist on the class.
 
 ## Lazy routes (real code-splitting)
 
@@ -286,8 +312,11 @@ export async function LoadAdminPage() {
 extern task<Component> LoadAdminPage() from "./admin_page_loader";
 nav.AddLazyRoute("/admin", LoadAdminPage);
 ```
-The lazy page is deliberately not `using`'d from your entry — that's what keeps it out of the
-eager bundle — so build it as its own entry too: `ks build src/app.ks && ks build src/admin_page.ks`.
+The lazy page (`admin_page.ks`) must be built as its own entry too — it's deliberately not
+`using`'d from your app's entry (that's what keeps it out of the eager bundle), so add a
+second build line: `ks build src/app.ks && ks build src/admin_page.ks`. Testing it via
+`kopular/testing`'s `runKopularApp` needs no extra setup — it compiles any file in your
+`srcDir` the entry doesn't reach.
 
 ## Testing
 
@@ -301,10 +330,12 @@ Real jsdom, real compile, real DOM assertions — not a mock.
 
 ## Common mistakes
 
-- Forgetting `this.` on a member inside a lambda — a real undefined-identifier error.
-- A `state<T>` where a plain `T` is expected needs `.Value` — including a `bool` returned from a
-  router guard or passed to `If()` (`KS4038`).
-- `if (x == null) { return; } use(x);` does **not** narrow `x`.
-- A two-way binding target must be a field path, never a method call.
-- `*mount` accepts only `id`/`[id]` on its element — anything else is a compile error, since the
-  mounted child's own `Render()` owns its content.
+- 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.
+- `*mount` accepts only `id`/`[id]` on its element — any other attr/binding is a compile
+  error, since the mounted child's own `Render()` owns all of its content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "1.2.3",
+  "version": "1.2.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",