kopular 1.0.1 → 1.1.0

package/GUIDE.md

@@ -0,0 +1,238 @@
+# 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`.
+
+## 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).
+
+```ks
+using "kopular";
+using "./counter";
+
+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.
+
+## 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 { 1 => "one", _ => "other" }` (the `_` arm is
+  required unless every case is covered, e.g. an enum).
+- Lambdas need explicit parameter types: `(number x) => x * 2`.
+- 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: `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)`.
+- `x == null` / `x != null` also match `undefined` — a missed `Array.Find`, an absent
+  optional field, etc. all read as `null`.
+- 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
+
+```ks
+class Counter : Component {
+  public state<number> Count;
+  constructor() : base() { this.Count = state(0); }
+  public void Increment() { this.Count.Value = this.Count.Value + 1; }
+  template from "./counter.html";
+}
+```
+```html
+<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.
+
+**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, `[(value)]="Field"` two-way binding
+(`Field` can be a bare name, `this.Field`, or a path like `Qty.Value` — not a method call),
+`*if="expr"`, `*for="Type v of expr"` (element type required, no inference), `*mount="expr"`
+(embeds a live child component, composes with `*for`).
+
+**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() {
+  VElement button = VElement.Create("button");
+  button.TextContent = "Count: " + this.Count.Value;
+  button.OnClick = (Event e) => { this.Increment(); };
+  return button;
+}
+```
+`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.
+
+**Error boundary**: override `RenderError(string message)` to show a fallback instead of an
+uncaught crash if `Render()` throws.
+
+## Nested components & content projection
+
+```ks
+this.Items.ForEach((Item item) => {
+  VElement slot = VElement.Mount(item);  // item : Component, e.g. its own `public string Id;`
+  slot.Id = item.Id;                     // stable key for reordering
+  list.AppendChild(slot);
+});
+```
+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, 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 everything once
+in a composition root:
+
+```ks
+class AppContainer {
+  public Router Nav;
+  constructor() {
+    CounterService counter = new CounterService();
+    this.Nav = new Router(new NotFoundPage());
+    this.Nav.AddRoute("/", new HomePage(this.Nav, counter));
+  }
+}
+```
+
+## Router
+
+```ks
+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; }
+  return true;
+});
+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; `guard` returns `false`
+  to redirect. 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.
+
+## Forms
+
+```ks
+FormField<string> email = new FormField<string>("", (string v) => {
+  string? required = Validators.Required(v);
+  if (required != null) { return required; }
+  return Validators.Email(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.
+
+## HTTP
+
+```ks
+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";`.
+
+## Async: `Delay`, `Computed`, `Resource<T>`
+
+```ks
+await Delay(500);  // real setTimeout-backed delay
+
+Computed2<number, number, number> total = new Computed2<number, number, number>(
+  qty, price, (number q, number p) => q * p
+);
+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
+match r.Status.Value {
+  AsyncStatus.Loading => BuildSpinner(),
+  AsyncStatus.Success => BuildContent(r.Data.Value),
+  AsyncStatus.Failure => BuildError(r.Error.Value)
+};
+```
+
+## Scoped styles
+
+```ks
+class Widget : Component {
+  template from "./widget.html";
+  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.
+
+## Lazy routes (real code-splitting)
+
+```js
+// admin_page_loader.js — hand-written, not compiled from .ks
+export async function LoadAdminPage() {
+  const { AdminPage } = await import("./admin_page.js");
+  return new AdminPage();
+}
+```
+```ks
+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.
+
+## Testing
+
+```js
+import { runKopularApp } from "kopular/testing";
+const { window, cleanup } = await runKopularApp(srcDir, "app.ks", { includeKopularPackage: true });
+// assert against window.document, then:
+cleanup();
+```
+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.
+- `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/LLM.md

@@ -1,10 +1,12 @@
 # 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 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.
+see `README.md` for narrative/rationale, or this package's own **`GUIDE.md`** for a short,
+task-oriented page covering everything a typical app needs (start there for most tasks;
+come back here for anything it doesn't cover). 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, `kopscript@1.1.0`+) — 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),
@@ -13,30 +15,50 @@ Published as npm `kopular`. Entry points: `kopular` / `kopular/component` (Compo
 (Computed1, Computed2), `kopular/resource` (Resource, AsyncStatus), `kopular/vdom`
 (`ScopedStyles` — the runtime half of `styles from`; everything else in this file, the
 diff/patch engine behind `Update()`, is internal, nothing else here needs importing
-directly), `kopular/testing` (runKopularApp, runKopularFixture — see below). 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
-from "./x.html";`, see below) are a KopScript language feature, not a Kopular export —
-there is no `kopular/template` entry point to import.
+directly), `kopular/timers` (`Delay`), `kopular/testing` (runKopularApp,
+runKopularFixture — see below). Also ships a bin, `kp` — `npx kp new <dir>` scaffolds a
+new project (an `index.html` with every module already wired, a `Counter` component, and
+the vendor/serve scripts needed to run in a browser). Templates (`template from
+"./x.html";`, see below) are a KopScript language feature, not a Kopular export — there is
+no `kopular/template` entry point to import.
 
 ## Consuming Kopular from your own KopScript project
 
-`using` only resolves same-project relative paths — reaching into an npm package (Kopular
-included) always goes through `extern`, re-describing exactly the members you use.
-
-**Don't reach for `Element`/`Document`/`Event` via `extern ... from "kopular/dom";`, even
-though that actually works** (`kopular/dom` genuinely re-exports real `globalThis`
-bindings, same as any other Kopular export) — **redeclare your own ambient block
-instead.** The reason isn't that importing wouldn't work; it's that Kopular's own internal
-`dom.ks` only declares what Kopular's own framework code itself touches, a smaller
-surface than a real app typically needs (`Element.value`/`.placeholder`, `.href`/`.src`/
-`.alt`, `.querySelector`, ...) — importing it would silently cap you at that subset with
-no signal you're missing something until you hit a real compile error for each one, one
-at a time. Every consuming project re-declares its own Element/Document/Event, same as
-this one does. **Copy the block below rather than hand-rolling a smaller one from scratch
-and adding members as compile errors demand them** — a real, complete first-attempt
+`using "kopular";` (`kopscript@1.1.0`+) resolves this package's own declarations —
+everything in the "Entry points" list above — through `node_modules`, the same way `npm
+install` already makes them available to plain JS. One line, every Kopular type in scope,
+each consuming file's own compiled output importing only the bindings it actually
+references (never the whole surface). This is the normal way to consume Kopular now; `kp
+new` generates it by default.
+
+```ks
+using "kopular";
+using "./counter";
+
+Counter app = new Counter();
+app.Mount(document.body);
+```
+
+`document`/`Element`/`Event`/etc. come from the same `using "kopular";` — no separate ambient
+block needed. The rest of this file describes every one of those bindings' real shapes, for
+when you need something `GUIDE.md` doesn't cover, or need to know exactly what a type looks
+like.
+
+### The hand-copied `extern` block (older projects, or trimming what you import)
+
+Before `kopscript@1.1.0`, every consuming project hand-declared its own copy of Kopular's
+`extern` bindings (`using` couldn't reach into a package). That still works — a real,
+hand-written `extern` block is exactly as valid as one resolved via `using "kopular";",
+just more to maintain — and is occasionally still the right call if you want a visibly
+trimmed subset. **Don't reach for `Element`/`Document`/`Event` via `extern ... from
+"kopular/dom";`, even though that actually works** (`kopular/dom` genuinely re-exports real
+`globalThis` bindings, same as any other Kopular export) — Kopular's own internal `dom.ks`
+only declares what Kopular's own framework code itself touches, a smaller surface than a
+real app typically needs. `using "kopular";`'s own declarations (`src/kopular.ks` in this
+package) don't have that problem — they're written for consumers, not just for Kopular's
+own internals — so prefer it over a hand-copied ambient block for new code. If you do
+hand-copy one anyway, copy the block below rather than hand-rolling a smaller one from
+scratch and adding members as compile errors demand them — a real, complete first-attempt
 implementation of a Kopular app hit the exact same missing property (`Element.value`)
 twice from two independently-trimmed subsets, because the compile error only ever names
 the one member actually touched, never warns that a *sibling* feature (a template's
@@ -95,6 +117,10 @@ extern class VElement {
   string Id { get; set; }
   string Value { get; set; }
   string RawHtml { get; set; }
+  // Real bool properties, not attribute strings — a boolean attribute is on
+  // whenever it's present at all, so only a real property can turn it back off.
+  bool Disabled { get; set; }
+  bool Checked { get; set; }
   (Event) => void OnClick { get; set; }
   (Event) => void OnInput { get; set; }
   (Event) => void OnBlur { get; set; }

package/README.md

@@ -836,11 +836,11 @@ error, not a runtime blank screen.
 
 ## Starting a new project: `kp new`
 
-Everything in the next section — the `extern` bindings, plus a `vendor/kopular/` copy of
-this package's browser files and an import map pointing at it (a browser can't resolve a
-bare specifier like `"kopular/component"` the way Node's own module resolution does) — is
-boilerplate every Kopular project needs verbatim. Generate it instead of reconstructing it
-by hand (or from memory, if you're an AI agent):
+`npx kp new my-app` scaffolds a real, working project: a `Counter` component
+(`src/counter.ks`), an `index.html` with every Kopular module already mapped, and the
+vendor/serve scripts needed to run in a browser (a browser can't resolve a bare specifier
+like `"kopular/component"` the way Node's own module resolution does, so `vendor-kopular.mjs`
+copies Kopular's runtime into `vendor/` and `index.html`'s import map points there).
 
 ```bash
 npx kp new my-app
@@ -849,37 +849,19 @@ npm install
 npm start   # builds, vendors kopular's browser files, and serves at :8080
 ```
 
-This scaffolds a real, working `Component` (`src/counter.ks` — the same Counter shown
-above), the ambient DOM/Kopular `extern` bindings it needs (`src/kopular_bindings.ks`),
-and a `README.md` that points an AI agent at this package's own `LLM.md` before it starts
+Its `README.md` points an AI agent at this package's own `GUIDE.md` before it starts
 generating code. `kp` ships from this package (not from `kopscript`'s own `ks` CLI) since
 scaffolding a *Kopular* app is a framework concern, not a language one — `ks` stays a
 pure-language tool with no framework knowledge baked in.
 
 ## Using Kopular from another KopScript project
 
-KopScript's own `using "./path";` only resolves relative paths within a project — it has
-no package-import mechanism yet. Cross-package consumption goes through `extern`
-instead, the same way KopScript already describes any other JS/npm dependency
-(`kp new` above generates exactly this, if you'd rather not hand-write it):
+`using "kopular";` (`kopscript@1.1.0`+) resolves this package's own KopScript declarations
+through `node_modules` — one line, every Kopular type in scope, with each file's own
+compiled output importing only what it actually references:
 
 ```ks
-extern class VElement {
-  static VElement Create(string tag);
-  string TextContent { get; set; }
-} from "kopular/velement";
-
-extern class Component {
-  constructor();
-  virtual VElement Render();
-  void Mount(Element parent);
-} from "kopular/component";
-
-extern class Router {
-  constructor(Component notFoundPage);
-  void AddRoute(string path, Component page);
-  void Navigate(string path);
-} from "kopular/router";
+using "kopular";
 
 class MyWidget : Component {
   public override VElement Render() {
@@ -890,19 +872,14 @@ class MyWidget : Component {
 }
 ```
 
-Marking `Render()` `virtual` in the `extern` declaration is what lets a real subclass
-`override` it — see [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
-for a full working example (components, a service, and routing, all consuming Kopular
-this way).
+See [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) for
+a full working example (components, a service, and routing).
 
-The snippet above is illustrative, not exhaustive — real code needs a fuller
-`VElement`/`Component`/`Router`, and `Element` itself (used above as `Mount`'s
-parameter type but never shown declared) is a plain ambient browser global your own
-project declares, not something Kopular exports — `LLM.md`'s "Consuming Kopular from
-your own KopScript project" section has the complete, copy-ready block for all of
-these, `Element`/`Document`/`Event` included. `npx kp new` (above) generates this
-boilerplate for a fresh project either way — reach for `LLM.md`'s block when adding to
-an existing one instead.
+Before `kopscript@1.1.0`, every project hand-declared its own copy of Kopular's `extern`
+bindings instead — `using` couldn't reach into a package yet. That still works (`kp new`
+above can generate it), and is still the right call if you want a visibly trimmed subset —
+see `LLM.md`'s "Consuming Kopular from your own KopScript project" for the complete,
+copy-ready block, `Element`/`Document`/`Event` included.
 
 `extern class` can carry its own `<T>` (kopscript >= 0.5.0), so a generic export like
 `FormField<T>` describes the same way a real generic class does — see `LLM.md`'s