kopular 0.13.0 → 0.15.0

package/LLM.md

@@ -1,15 +1,18 @@
 # Kopular — LLM reference
 
 Complete reference for generating correct Kopular code. This is a spec, not a tutorial —
-see `README.md` for narrative/rationale. Kopular is 8 files total; this covers all of
-them. For the host language, see KopScript's own `LLM.md` in the `Kop` repo (or its
+see `README.md` for narrative/rationale. Kopular is 10 files total; this covers all of
+them. For the host language, see KopScript's own `LLM.md` in the `KopScript` repo (or its
 published `LLM.md` on the `kopscript` npm package) — that reference is a prerequisite,
 not repeated here.
 
 Published as npm `kopular`. Entry points: `kopular` / `kopular/component` (Component),
+`kopular/velement` (VElement — what `Render()` returns; see "Component" below),
 `kopular/router` (Router), `kopular/dom` (ambient DOM bindings), `kopular/directives`
 (If), `kopular/http` (Http), `kopular/forms` (FormField, Validators), `kopular/testing`
-(runKopularApp, runKopularFixture — see below). Also ships a bin, `kp` — `npx kp new
+(runKopularApp, runKopularFixture — see below). `kopular/vdom` (the diff/patch engine
+behind `Update()`) is internal — nothing outside `component.ks` needs to import it
+directly. Also ships a bin, `kp` — `npx kp new
 <dir>` scaffolds a new project (the `extern` bindings below, plus the vendor/serve
 scripts needed to run in a browser) rather than requiring it be reconstructed by hand;
 prefer it over hand-writing the section below for a new project. Templates (`template
@@ -22,9 +25,25 @@ there is no `kopular/template` entry point to import.
 included) always goes through `extern`, re-describing exactly the members you use:
 
 ```ks
+extern class VElement {
+  static VElement Create(string tag);
+  string TextContent { get; set; }
+  string ClassName { get; set; }
+  string Id { get; set; }
+  string Value { get; set; }
+  string RawHtml { get; set; }
+  (Event) => void OnClick { get; set; }
+  (Event) => void OnInput { get; set; }
+  (Event) => void OnBlur { get; set; }
+  (Event) => void OnChange { get; set; }
+  void AppendChild(VElement child);
+  void SetAttr(string name, string value);
+} from "kopular/velement";
+
 extern class Component {
   constructor();
-  virtual Element Render();       // `virtual` here is what lets your subclass `override` it
+  virtual VElement Render();      // `virtual` here is what lets your subclass `override` it
+  virtual void AfterRender(Element root); // see "Component" below
   void Mount(Element parent);
   void Update();
 } from "kopular/component";
@@ -36,7 +55,7 @@ extern class Router {
   void Mount(Element parent);
 } from "kopular/router";
 
-extern Element If(bool condition, () => Element whenTrue, () => Element whenFalse) from "kopular/directives";
+extern VElement If(bool condition, () => VElement whenTrue, () => VElement whenFalse) from "kopular/directives";
 
 extern class Response {
   bool ok { get; }
@@ -86,7 +105,7 @@ Kopular's own copy in `dom.ks` isn't reachable across the package boundary; rede
 handful of members you actually use. See KopularDemo's `src/kopular_bindings.ks` for a
 complete, real example of both.
 
-## `Component` (`component.ks`)
+## `Component` (`component.ks`, `velement.ks`, `vdom.ks`) — real vdom diffing
 
 ```ks
 class MyWidget : Component {
@@ -96,46 +115,68 @@ class MyWidget : Component {
     this.count = 0;
   }
 
-  public override Element Render() {
-    Element el = document.createElement("div");
-    el.textContent = "Count: " + this.count;
+  public override VElement Render() {
+    VElement el = VElement.Create("div");
+    el.TextContent = "Count: " + this.count;
     return el;
   }
 
   public void Bump() {
     this.count = this.count + 1;
-    this.Update();       // re-runs Render(), swaps the old root for the new one
+    this.Update();       // re-runs Render(), diffs it against the previous tree, patches real DOM
   }
 }
 
 MyWidget w = new MyWidget();
-w.Mount(document.body);  // first Render() + append
-w.Bump();                // re-render
+w.Mount(document.body);  // first Render() + materialize + append
+w.Bump();                // re-render + diff + patch
 ```
 
-- `Render()`: `virtual`, override it to build a fresh DOM subtree from current state.
-  Called by both `Mount()` and `Update()`. **No diffing either way** — every call
-  rebuilds the whole subtree from scratch. Provide it as a real markup file via
-  KopScript's `template from "./x.html";` (see "Templates" below) instead of hand-writing
-  it — both produce the exact same method; Kopular needed no code changes to support this.
-- `Mount(parent)`: calls `Render()` once, appends the result to `parent`, remembers both
-  for `Update()` to use later.
+- `Render()`: `virtual`, override it to describe the current state as a `VElement` tree —
+  a lightweight description of a DOM element (`kopular/velement`), not a real one. Called
+  by both `Mount()` and `Update()`. Provide it as a real markup file via KopScript's
+  `template from "./x.html";` (see "Templates" below) instead of hand-writing it — both
+  produce the exact same method; Kopular needed no framework code changes to support this.
+- `VElement`: `Tag`, `TextContent`/`ClassName`/`Id`/`Value` (direct fields — `Value` is the
+  one that must be a live DOM *property*, not an attribute: `SetAttr("value", x)` sets the
+  default value, not the current one), `RawHtml` (an opaque, undiffed leaf — set instead of
+  `TextContent`/children, for a raw-HTML-then-wire-handlers pattern), the four fixed named
+  event fields `OnClick`/`OnInput`/`OnBlur`/`OnChange` (each a real no-op by default, never
+  null — no nullable function type to fall back on), `AppendChild(child)`, and
+  `SetAttr(name, value)` (the escape hatch for any other real HTML attribute — `href`,
+  `src`, `alt`, `placeholder`, ...; never `Value`, see above). `Id` doubles as a stable key
+  for list-child reconciliation — see `PatchChildren` below.
+- `Mount(parent)`: calls `Render()` once, materializes the returned tree into real DOM
+  (`Materialize` in `vdom.ks`), appends it to `parent`, then calls `AfterRender(root)`.
 - `Update()` (protected — called from within the component, not externally): calls
-  `Render()` again and `replaceChild`s the old root with the new one.
-- **Known limitation**: if a *parent* component's `Update()` runs while it has mounted
-  children, those children are NOT automatically re-mounted into the new parent tree —
-  `Component` only handles a single component's own re-render cycle, not tree
-  reconciliation. Compose independent components into stable slots (see `Router`'s own
-  pattern of keeping page instances alive) to avoid this rather than nesting components
-  that both re-render.
+  `Render()` again and `Patch`es the new tree against the previous one (`vdom.ks`), reusing
+  a real DOM node wherever a node's tag stays the same instead of rebuilding it — sibling
+  nodes untouched by the change keep their exact identity (`===`), not just their content.
+  A list child without a stable `Id` still ends up correct after a reorder, but isn't
+  guaranteed to keep its own real node (see `PatchChildren`'s keyed-vs-positional matching
+  in `vdom.ks`). Then calls `AfterRender(root)`.
+- `AfterRender(root)`: `virtual`, a no-op by default, called at the end of both `Mount()`
+  and `Update()` with the real, now-materialized/patched root `Element`. For a component
+  that needs to do further imperative work against its own real DOM — most commonly,
+  mounting a *nested* `Component` into a slot `Render()`'s tree just describes as data,
+  since a live mounted child isn't something `VElement` can express (see `Router`'s own
+  use of this to mount its matched page into the outlet, and "Dependency injection" below
+  for `RoutedApp` doing the same with `Router` itself).
+- **Known limitation**: reconciliation is per-`Component`, not across nested ones — if a
+  *parent* component's own `Render()` output changes shape around a slot where a nested
+  Component was `Mount()`ed via `AfterRender`, that nested Component isn't automatically
+  re-`Mount()`ed or torn down as part of the parent's diff. Compose independent components
+  into a stable, unchanging slot (see `Router`'s own outlet, which never changes tag or
+  position) to avoid this rather than nesting components whose *surrounding* structure
+  also changes.
 - **`Update()` before `Mount()` is a safe no-op**, not an error. This matters for two
   sibling `Component`s (e.g. two `Router` pages) that share one injected service's
   `state<T>` and both `Subscribe()` it — every route's page is constructed eagerly (see
   `Router.AddRoute`), so at any given time most of them are constructed but never
   `Mount()`ed. Changing that shared state fires `Subscribe` on all of them, including the
-  ones that aren't the currently-routed page — `Update()` just skips the render/replace
-  for those, since `Mount()` will run a fresh `Render()` anyway whenever one of them
-  actually becomes routed.
+  ones that aren't the currently-routed page — `Update()` just skips the render/patch for
+  those, since `Mount()` will run a fresh `Render()` anyway whenever one of them actually
+  becomes routed.
 - `RenderError(string message)`: `virtual`, called by `Mount()`/`Update()` (via a private
   `SafeRender()` wrapper) when `Render()` throws, instead of letting the exception
   propagate uncaught and crash whatever triggered the render (a click handler, a `Router`
@@ -143,9 +184,9 @@ w.Bump();                // re-render
   opt-in error recovery**; a `Component` that never overrides `RenderError` behaves
   exactly as before this existed. Override it to show a fallback UI instead:
   ```ks
-  protected override Element RenderError(string message) {
-    Element el = document.createElement("div");
-    el.textContent = "Something went wrong: " + message;
+  protected override VElement RenderError(string message) {
+    VElement el = VElement.Create("div");
+    el.TextContent = "Something went wrong: " + message;
     return el;
   }
   ```
@@ -170,16 +211,22 @@ class Counter : Component {
 
 - `{{ expr }}` interpolation, `(event)="stmt"`, `[prop]="expr"`, `*if="expr"`,
   `*for="Type varName of expr"` — all real KopScript, checked at compile time, desugared
-  to the exact same `document.createElement`/`.appendChild`/`.textContent`/
-  `.addEventListener` calls a hand-written `Render()` would use.
+  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.
 - A `state<T>` field declared directly on the class and referenced directly in the
   template (`Count` above) gets `Subscribe((v) => this.Update())` wired automatically —
   no manual `Subscribe` in the constructor for that field. State reached indirectly
   (through a method, or `this.SomeService.Count`) still needs a manual `Subscribe`, same
   as a hand-written `Render()` always has.
+- **Two-way binding**: `[(value)]="Field"` desugars to `[value]="Field"` +
+  `(input)="Field = e.target.value"` — `value` only, and `Field` must be a bare name or
+  `this.Field` (see KopScript's own LLM.md `KS5017`/`KS5018` for the two rejected cases).
 - One top-level element per template (hard error otherwise); no mixing text and element
-  children under one element (no text-node type in `dom.ks`, only `.textContent`); no
-  two-way binding, no pipes, at most one structural directive per element.
+  children under one element (`VElement` has no text-node sibling concept, only
+  `.TextContent`); no pipes, at most one structural directive per element.
 - This is entirely a KopScript compiler feature (parsed/desugared before type-checking
   runs) — Kopular's own framework code (`component.ks`, `dom.ks`) is unmodified and
   unaware templates exist; a template-generated `Render()` is indistinguishable from a
@@ -191,14 +238,14 @@ Real URLs via the History API (`pushState`/`popstate`), not hash routing.
 
 ```ks
 class NotFoundPage : Component {
-  public override Element Render() { /* ... */ }
+  public override VElement Render() { /* ... */ }
 }
 class HomePage : Component {
   private Router Nav;
   constructor(Router nav) : base() { this.Nav = nav; }
-  public override Element Render() {
-    Element btn = document.createElement("button");
-    btn.addEventListener("click", (Event e) => { this.Nav.Navigate("/about"); });
+  public override VElement Render() {
+    VElement btn = VElement.Create("button");
+    btn.OnClick = (Event e) => { this.Nav.Navigate("/about"); };
     return btn;
   }
 }
@@ -238,14 +285,14 @@ nav.Navigate("/about");                          // pushState + immediate re-ren
   `"/search?sort=name"` -> `Query("sort") == "name"`. Values are **not percent-decoded** —
   no `decodeURIComponent` binding exists yet, a deliberate v1 cut; `%20`/`+` arrive
   exactly as written in the URL, not converted to a space.
-- **Why `Param` is a plain field, not `state<T>`**: `Render()` already rebuilds a fresh
-  outlet and re-`Mount()`s the matched page on every `Navigate()`/`popstate`, which
+- **Why `Param` is a plain field, not `state<T>`**: `Router`'s own `AfterRender` already
+  re-`Mount()`s the matched page into its outlet on every `Navigate()`/`popstate`, which
   re-runs that page's own `Render()` (reading the fresh `Param`) with no extra step.
   Making it `state<T>` and having a page `Subscribe()` to it — the pattern every *other*
   piece of state in this framework uses — actually crashes: `Match()` sets it *before*
-  `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.
+  `AfterRender` finishes mounting 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 patch 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 —
@@ -282,11 +329,11 @@ a **hand-written** `Render()`, where `if` being a statement (not an expression)
 conditional value needs a helper to get one out of it:
 
 ```ks
-Element If(bool condition, () => Element whenTrue, () => Element whenFalse)
+VElement If(bool condition, () => VElement whenTrue, () => VElement whenFalse)
 ```
 
 ```ks
-root.appendChild(If(this.IsLoggedIn, () => this.BuildProfile(), () => this.BuildLogin()));
+root.AppendChild(If(this.IsLoggedIn, () => this.BuildProfile(), () => this.BuildLogin()));
 ```
 
 Both branches always required (no null "nothing" value); only the branch actually taken
@@ -295,20 +342,22 @@ at all in hand-written `Render()` either:
 
 ```ks
 // *ngFor — plain array method
-this.Items.ForEach((Item item) => { list.appendChild(this.BuildItemRow(item)); });
+this.Items.ForEach((Item item) => { list.AppendChild(this.BuildItemRow(item)); });
 
 // *ngSwitch — plain KopScript `match` expression (exhaustiveness-checked, unlike *ngSwitch)
-root.appendChild(match this.Status {
+root.AppendChild(match this.Status {
   "loading" => this.BuildSpinner(),
   "error" => this.BuildError(),
   _ => this.BuildContent()
 });
 ```
 
-No keyed/reuse-existing-DOM-nodes diffing (the performance angle of `*ngFor trackBy`) —
-that needs comparing old/new data by a caller key, generic over item type, and KopScript
-has no generics. Not planned as a workaround; would need real language-level generics
-first.
+**Keyed/reuse-existing-DOM-nodes diffing (the `*ngFor trackBy` angle) exists** — give each
+item's `VElement` a stable `.Id` (e.g. the item's own id) and `Update()`'s diff engine
+(`PatchChildren` in `vdom.ks`) matches children by `Id` across a re-render, reusing a
+matched child's real DOM node rather than rebuilding it. Without a stable `Id`, a
+reordered list still renders correctly, but a given item's real node isn't guaranteed to
+follow its data.
 
 ## `Http` (`http.ks`) — thin wrapper over `fetch`
 
@@ -367,7 +416,7 @@ email.Valid();                  // bool — Error.Value == null
 after the first as a nested function type, not an array element type, and errors expecting
 `=>`). Combine checks as an if-chain in one lambda (see the `email` example above), or via
 the fixed-arity `CombineValidators2<T>`/`CombineValidators3<T>` free functions (generic,
-inference-only — see `Kop`'s own "Generics" docs for why they're *free* functions, not
+inference-only — see `KopScript`'s own "Generics" docs for why they're *free* functions, not
 `Validators` static methods):
 ```ks
 CombineValidators2((string v) => Validators.Required(v), (string v) => Validators.Email(v))
@@ -376,13 +425,12 @@ CombineValidators2((string v) => Validators.Required(v), (string v) => Validator
 Fixed-arity (2, 3 — add more the same way if a form ever needs to chain further), not a
 general `Validators.All(...)`, for the same array-of-function-values reason above.
 
-**No DOM binding** — wiring `.Value` to a real `<input>` is a plain `addEventListener`
-call in your own `Render()`, the same as any other event handler; there is no
-`[(ngModel)]`-equivalent.
-
-**No DOM binding** — wiring `.Value` to a real `<input>` is a plain `addEventListener`
-call in your own `Render()`, the same as any other event handler; there is no
-`[(ngModel)]`-equivalent.
+**No DOM binding in a hand-written `Render()`** — wiring `.Value` to a real `<input>` is a
+plain `VElement.OnInput` assignment reading `e.target.value` (the same as any other event
+handler; `VElement.Value` itself is one-way, host-to-DOM only), and reading it back out
+via `.Touch()` on `OnBlur`. A **template** has real `[(value)]="Field"` sugar for the
+value-binding half (see "Templates" above); `Touch()` on blur still needs its own explicit
+`(blur)="Field.Touch()"` either way — `[(value)]` only ever wires `value`/`input`.
 
 ## `kopular/testing` (`testing.js`, hand-written JS, not compiled from `.ks`)
 
@@ -435,10 +483,14 @@ class AppContainer {
 class RoutedApp : Component {
   private Router Nav;
   constructor(AppContainer services) : base() { this.Nav = services.Nav; }
-  public override Element Render() {
-    Element el = document.createElement("div");
-    this.Nav.Mount(el);
-    return el;
+  public override VElement Render() {
+    return VElement.Create("div");
+  }
+  // Mounting Router — a live, nested Component — isn't something a VElement
+  // tree can express as data; AfterRender gets the real, now-materialized
+  // root Element instead (see "Component" above).
+  protected override void AfterRender(Element root) {
+    this.Nav.Mount(root);
   }
 }
 
@@ -462,8 +514,8 @@ class CounterService {
 - **`Router.Param` is a plain `string`, not `state<T>` — don't `Subscribe()` to it.** A
   `state<T>`-based design for it was tried and genuinely crashes: `Navigate()` sets `Param`
   *before* the newly-matched page finishes mounting, so a page `Subscribe`-ing to it fires
-  while its own `Update()` still has no `ParentElement` to `replaceChild` into. `Render()`
-  already re-reads the fresh `Param` on every navigation with no extra step — just read
+  while its own `Update()` still has no `ParentElement` to patch into. `Render()` already
+  re-reads the fresh `Param` on every navigation with no extra step — just read
   `this.Nav.Param` directly inside `Render()`.
 - **Deploying a `Router`-based app needs SPA/history-fallback configured on the actual host**
   — this bit the real `KopularDemo` production site (worked when navigated to via a link,
@@ -480,19 +532,37 @@ class CounterService {
   independent mechanisms, not the same thing wired two ways** — a template never needs
   `directives.ks`'s `If()` imported or called; `*if`/`*for` compile to real `if`/`for`
   directly. Don't mix a template with a hand-written-`Render()` helper call.
-- **No two-way binding, anywhere.** Wiring a template's `[value]` or a hand-written
-  `.Value` to a real `<input>` back and forth always needs an explicit
-  `addEventListener("input", ...)` — there's no `[(ngModel)]`-equivalent to reach for in
-  either authoring style.
+- **`[(value)]` two-way binding is template-only, and `value`-only.** A hand-written
+  `Render()` still always needs an explicit `OnInput` assignment reading
+  `e.target.value` — there's no equivalent shorthand there, since it already has direct
+  field access. `[(id)]`/`[(className)]` don't exist either, even in a template — the
+  sugar only wires `value`/`input`, the one pairing with a real "user just changed this"
+  event.
+- **A `VElement` event binding only accepts `click`/`input`/`blur`/`change`** — both in a
+  template's `(event)="..."` and a hand-written `OnClick`/`OnInput`/`OnBlur`/`OnChange`
+  assignment. There's no generic `addEventListener` on `VElement` (event handlers are part
+  of the tree's own data, not wired against a live DOM node until `Materialize`/`Patch`
+  runs) — an event Kopular doesn't have a named field for isn't reachable from `Render()`
+  at all yet.
+- **Reconciliation doesn't cross a `Mount()`ed-via-`AfterRender` boundary.** Real vdom
+  diffing patches one `Component`'s own subtree; a *nested* Component mounted into a slot
+  via `AfterRender` (see `Router`'s outlet, or `RoutedApp` mounting `Router` itself) isn't
+  automatically re-`Mount()`ed if the *parent's* surrounding tree shape changes — see
+  "Component"'s own "Known limitation" above.
 
 ## Does not exist
 
 DI container/injector · decorators (`@Injectable`, `@Component`, ...) · a runtime
 template engine or interpreted expression language — templates compile to the same
 imperative `Render()` code as the hand-written form, checked at compile time, not
-interpreted at runtime (see "Templates" above) · two-way binding (`[(ngModel)]`) ·
-vdom diffing / reconciliation beyond a single component's own re-render · pipes ·
-animations · typed/generic HTTP responses (`Http` returns raw text — see above) · SSR.
+interpreted at runtime (see "Templates" above) · two-way binding in a hand-written
+`Render()`, or on anything but `value` even in a template (`[(value)]="Field"` exists —
+see "Templates" above — but it's `value`-only, and templates-only) ·
+reconciliation across a nested-Component boundary (see "Common mistakes" above — real
+vdom diffing exists *within* one Component's own subtree, via `Update()`/`vdom.ks`) ·
+a generic/arbitrary `VElement` event binding — only `click`/`input`/`blur`/`change` ·
+pipes · animations · typed/generic HTTP responses (`Http` returns raw text — see above) ·
+SSR.
 
 (`FormField<T>`/`Validators` and `kp new` — see "FormField<T> / Validators" and "Starting
 a new project" above — are real, shipped features; they used to be listed here as gaps