kopular 1.2.1 → 1.2.3

package/GUIDE.md

@@ -1,14 +1,13 @@
 # Kopular quick guide
 
-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`.
+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`.
 
 ## Setup
 
-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).
+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.
 
 ```ks
 using "kopular";
@@ -18,71 +17,51 @@ Counter app = new Counter();
 app.Mount(document.body);
 ```
 
-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.
+`npm start` builds and serves; `ks check src/app.ks` type-checks without building.
 
 ## The language you need
 
-- `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.
+- `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`.
 - 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`.
+- 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`).
 - `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
-  `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),
+  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),
   `.Slice(a, b)/.Concat(ys)/.Join(sep)/.Reduce(fn, initial)`.
-- `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:
+- **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:
   ```ks
   bool isLetter = match c { r"^[a-z]$" => true, _ => false };
   ```
-  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.
+  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.
 
 ## Components
 
@@ -98,21 +77,20 @@ class Counter : Component {
 <button (click)="Increment()">Count: {{ Count.Value }}</button>
 ```
 
-`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.
+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());`
 
 **Template bindings**: `{{ expr }}` text, `[prop]="expr"` (real fields for
-`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):
+`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`:
 ```ks
 public state<string> Qty;
 constructor() : base() { this.Qty = state("1"); }
@@ -121,8 +99,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 top-level pieces in one real container element:
+**Exactly one top-level element per template** — no auto-wrapping, a hard compile error
+otherwise. Wrap multiple pieces in one container:
 ```html
 <div>
   <input id="text" [(value)]="Draft" />
@@ -130,8 +108,7 @@ otherwise.** Wrap multiple top-level pieces in one real container element:
 </div>
 ```
 
-**Hand-written `Render()`** (needed when logic is too dynamic for a template, or a template
-would obscure more than it clarifies):
+**Hand-written `Render()`**, for logic too dynamic for a template:
 
 ```ks
 public override VElement Render() {
@@ -142,18 +119,17 @@ 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 across a project.
+`.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.
 
-**Conditional value**: there's no ternary, so to pick between two elements use `If()` (from
+**Conditional value**: 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.
+**Error boundary**: override `RenderError(string message)` for a fallback instead of an uncaught
+crash when `Render()` throws.
 
 ## Nested components & content projection
 
@@ -164,15 +140,15 @@ this.Items.ForEach((Item item) => {
   list.AppendChild(slot);
 });
 ```
-A template does the same via `<li *for="Item i of Items" *mount="i"></li>`.
+A template does the same with `<li *for="Item i of Items" *mount="i"></li>`.
 
-Content projection (React's `children`): pass a `() => VElement` into a constructor, call
-it from `Render()` — no separate mechanism needed.
+Content projection (React's `children`): pass a `() => VElement` into a constructor and call it
+from `Render()`.
 
 ## Services — no DI container
 
-A service is a plain class; "injecting" it is a constructor argument. Wire everything once
-in a composition root:
+A service is a plain class; "injecting" it is a constructor argument. Wire it once in a
+composition root:
 
 ```ks
 class AppContainer {
@@ -198,19 +174,16 @@ nav.SetGuard("/login", (string path) => {
 nav.Navigate("/dogs/1");
 nav.Mount(document.body);
 ```
-- 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.
+- 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.
 - 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.
+  matching file). That's an HTTP limitation, not a Kopular one.
 
 ## Forms
 
@@ -223,8 +196,9 @@ 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 returns an error message
-or `null`. No array-of-validators param — chain checks in one lambda, as above.
+`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`.
 
 ## HTTP
 
@@ -233,9 +207,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 {
@@ -246,8 +220,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() {
@@ -296,8 +270,8 @@ class Widget : Component {
   styles from "./widget.css";
 }
 ```
-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.
+Every selector in `widget.css` is rewritten to match only this class's own elements. The class
+must have a constructor.
 
 ## Lazy routes (real code-splitting)
 
@@ -312,11 +286,8 @@ export async function LoadAdminPage() {
 extern task<Component> LoadAdminPage() from "./admin_page_loader";
 nav.AddLazyRoute("/admin", LoadAdminPage);
 ```
-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.
+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`.
 
 ## Testing
 
@@ -330,12 +301,10 @@ Real jsdom, real compile, real DOM assertions — not a mock.
 
 ## Common mistakes
 
-- 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.
+- 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.

package/LLM.md

@@ -442,8 +442,10 @@ class Counter : Component {
   to the exact same `VElement.Create`/`.AppendChild`/`.TextContent`/named-event-field
   calls a hand-written `Render()` would use. `(event)` only accepts `click`/`input`/
   `blur`/`change` — `VElement`'s own fixed set — anything else is a compile error
-  (`KS5016`). `[prop]`/static `attr="..."` assign directly for `id`/`className`/`value`;
-  anything else goes through `SetAttr` instead.
+  (`KS5016`). `[prop]`/static `attr="..."` assign directly for `id`/`className`/`value`
+  **and the two real bool fields, `disabled`/`checked`** (the compiler's own
+  `BOOL_FIELD_NAMES` map — a boolean attribute is present-or-absent, so only a real
+  property can turn one back off); anything else goes through `SetAttr` instead.
 - **`*mount="expr"`** embeds a live child Component declaratively — desugars to
   `VElement.Mount(expr)`, the same mechanism a hand-written `Render()` uses (see "Nested
   component composition" below). Unlike `*if`/`*for`, it composes with either — `*for="Row

package/package.json

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