kopular 0.2.0 → 0.3.0

package/LLM.md

@@ -0,0 +1,198 @@
+# 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 4 files total; this covers all of
+them. For the host language, see KopScript's own `LLM.md` in the `Kop` 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/router` (Router), `kopular/dom` (ambient DOM bindings), `kopular/directives` (If).
+
+## 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:
+
+```ks
+extern class Component {
+  constructor();
+  virtual Element Render();       // `virtual` here is what lets your subclass `override` it
+  void Mount(Element parent);
+  void Update();
+} from "kopular/component";
+
+extern class Router {
+  constructor(Component notFoundPage);
+  void AddRoute(string path, Component page);
+  void Navigate(string path);
+  void Mount(Element parent);
+} from "kopular/router";
+
+extern Element If(bool condition, () => Element whenTrue, () => Element whenFalse) from "kopular/directives";
+```
+
+You also need your own ambient DOM `extern` block (`document`, `Element`, `Event`, ...) —
+Kopular's own copy in `dom.ks` isn't reachable across the package boundary; redeclare the
+handful of members you actually use. See KopularDemo's `src/kopular_bindings.ks` for a
+complete, real example of both.
+
+## `Component` (`component.ks`)
+
+```ks
+class MyWidget : Component {
+  private number count;
+
+  constructor() : base() {
+    this.count = 0;
+  }
+
+  public override Element Render() {
+    Element el = document.createElement("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
+  }
+}
+
+MyWidget w = new MyWidget();
+w.Mount(document.body);  // first Render() + append
+w.Bump();                // re-render
+```
+
+- `Render()`: `virtual`, override it to build a fresh DOM subtree from current state.
+  Called by both `Mount()` and `Update()`. **No template language, no diffing** — every
+  call rebuilds the whole subtree from scratch.
+- `Mount(parent)`: calls `Render()` once, appends the result to `parent`, remembers both
+  for `Update()` to use later.
+- `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.
+
+## `Router` (`router.ks`)
+
+Real URLs via the History API (`pushState`/`popstate`), not hash routing.
+
+```ks
+class NotFoundPage : Component {
+  public override Element 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"); });
+    return btn;
+  }
+}
+
+Router nav = new Router(new NotFoundPage());   // NotFoundPage REQUIRED up front — no null route
+nav.AddRoute("/", new HomePage(nav));           // pages built once, kept alive for Router's lifetime
+nav.AddRoute("/about", new AboutPage(nav));
+nav.Mount(document.body);
+nav.Navigate("/about");                          // pushState + immediate re-render
+```
+
+- Constructor takes the fallback page (`Component`), required — there's no nullable
+  "no match" representation.
+- `AddRoute(path, page)` takes an **already-constructed `Component` instance**, not a
+  factory — every registered page is built once and stays alive for the Router's whole
+  lifetime, so a page's own `state<T>` fields survive navigating away and back.
+- `Navigate(path)` calls `history.pushState` then re-renders immediately. A browser
+  back/forward triggers re-render via a `popstate` listener registered in the
+  constructor — `Navigate()` itself doesn't rely on that event.
+- Needs a server that falls back to the app shell for any unrecognized path (a plain
+  static server has nothing to serve at `/about` on direct load/refresh).
+
+## `If` (`directives.ks`) — the `*ngIf` equivalent
+
+```ks
+Element If(bool condition, () => Element whenTrue, () => Element whenFalse)
+```
+
+```ks
+root.appendChild(If(this.IsLoggedIn, () => this.BuildProfile(), () => this.BuildLogin()));
+```
+
+Both branches always required (no null "nothing" value); only the branch actually taken
+is called — the other lambda never runs. `*ngFor` and `*ngSwitch` need no Kopular helper
+at all:
+
+```ks
+// *ngFor — plain array method
+this.Items.ForEach((Item item) => { list.appendChild(this.BuildItemRow(item)); });
+
+// *ngSwitch — plain KopScript `match` expression (exhaustiveness-checked, unlike *ngSwitch)
+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.
+
+## Dependency injection — no container, no decorators
+
+There is no injector, no `@Injectable`, no provider tokens. "Injecting" a service is
+passing it as a constructor argument — the compiler enforces it (a missing/mistyped
+dependency is a build error). For an app with more than a couple of services, use one
+plain "composition root" class (not a `Component`, never touches the DOM) that builds
+the whole service/page graph exactly once and hands the finished pieces to whatever
+needs them:
+
+```ks
+class AppContainer {
+  public Router Nav;
+  constructor() {
+    CounterService counter = new CounterService();   // shared singleton: pass the same
+    this.Nav = new Router(new NotFoundPage());        // instance wherever it should be
+    this.Nav.AddRoute("/", new HomePage(this.Nav, counter));
+  }
+}
+
+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;
+  }
+}
+
+RoutedApp app = new RoutedApp(new AppContainer());
+app.Mount(document.body);
+```
+
+A service needing its own state/logic is a plain class — no base class, no
+decorators, nothing framework-specific:
+
+```ks
+class CounterService {
+  public state<number> Count;
+  constructor() { this.Count = state(0); }
+  public void Increment() { this.Count.Value = this.Count.Value + 1; }
+}
+```
+
+## Does not exist
+
+DI container/injector · decorators (`@Injectable`, `@Component`, ...) · a template
+language/DSL — everything is imperative `Render()` code against plain DOM bindings ·
+vdom diffing / reconciliation beyond a single component's own re-render · pipes ·
+animations · forms/validation module · HTTP client · a CLI/scaffolding tool (`ng
+generate`-equivalent) · SSR.

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://cdn.jsdelivr.net/npm/kopular@latest/assets/logo.png" width="96" height="96" alt="Kopular logo">
+
 # Kopular
 
 Kopular is a small component framework for [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/Kop),
@@ -5,6 +7,9 @@ built to give Angular's separation of concerns — components own UI, services o
 a router owns navigation — without Angular's steepest learning-curve pieces: no RxJS, no
 dependency-injection container, no template DSL.
 
+Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./LLM.md)**
+— a dense, complete reference designed to be loaded straight into an LLM's context.
+
 ## Highlights
 
 - **`Component`**: a base class with `virtual Render()` (builds a fresh DOM subtree from
@@ -24,16 +29,155 @@ dependency-injection container, no template DSL.
   DSL. Needs a server that falls back to the app shell for unrecognized paths — see
   [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)'s
   `scripts/serve.mjs`.
+- **Structural directives, no template DSL**: `*ngIf`/`*ngFor`/`*ngSwitch`'s job — build
+  a subtree conditionally, repeat one per item, pick one of several cases — done as plain
+  function calls (`If(...)`) and existing KopScript expressions (`array.ForEach(...)`,
+  `match`), not special template syntax. See "Structural directives" below.
 
 ## What's here
 
 - `src/dom.ks` — ambient DOM bindings (`document`, `Element`, `Event`, `window`,
-  `location`) that `component.ks`/`router.ks` are built on.
+  `location`) that `component.ks`/`router.ks`/`directives.ks` are built on.
 - `src/component.ks` — the `Component` base class.
 - `src/router.ks` — the `Router`.
+- `src/directives.ks` — `If()`, the structural-directive equivalents' one genuinely new
+  piece (see below).
+
+That's the whole framework — four files. Everything else (a real app built on top of it)
+lives in a separate consumer repo, [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo).
+
+## Dependency injection: the composition root pattern
+
+Kopular has no injector because KopScript has nothing for one to hook into — no
+decorators, no reflection, no generics for a type-safe `Resolve<T>()`. Instead, the
+whole app's service/page graph gets built exactly once, by hand, in one place: a plain
+class with no `Component` base and no framework code in it at all, sometimes called an
+**app container** or (in the wider DI literature) a **composition root**. Everything
+else just takes what it needs as constructor arguments and never constructs its own
+dependencies.
+
+```ks
+// app_container.ks — the one place that decides what's shared and builds
+// the graph, in dependency order.
+class AppContainer {
+  public Router Nav;
+
+  constructor() {
+    // Built once, passed to every page that needs it below — that's the
+    // whole mechanism for a shared singleton. A page that constructed its
+    // own `new CounterService()` instead would get an independent one; the
+    // difference is which variable gets passed in, not a config flag.
+    CounterService counter = new CounterService();
+
+    this.Nav = new Router(new NotFoundPage());
+    this.Nav.AddRoute("/", new HomePage(this.Nav, counter));
+    this.Nav.AddRoute("/about", new AboutPage(this.Nav));
+  }
+}
+
+// routed_app.ks — the root Component. Takes the already-built graph; never
+// builds one of its own.
+class RoutedApp : Component {
+  private Router Nav;
+
+  constructor(AppContainer services) : base() {
+    this.Nav = services.Nav;
+  }
+
+  public override Element Render() {
+    Element container = document.createElement("div");
+    this.Nav.Mount(container);
+    return container;
+  }
+}
+
+RoutedApp app = new RoutedApp(new AppContainer());
+app.Mount(document.body);
+```
+
+This is sometimes called "Pure DI" — the same benefits a container gives you (nothing
+hardcodes its own dependencies, everything is swappable in a test) with none of a
+container's cost:
+
+- **Compile-time checked.** A missing or mistyped dependency is `expected N arguments,
+  got M` from the KopScript compiler, not a `NullInjectorError` your users hit at
+  runtime after a container fails to resolve something.
+- **Fully legible.** The entire dependency graph is ordinary, readable code in one file
+  — grep for `new` in the composition root and you've read the whole wiring diagram.
+  Nothing is constructed by a framework inspecting metadata behind the scenes.
+- **No new concepts.** If you already know how to call a constructor, you already know
+  Kopular's DI story — there's no separate injector API, provider syntax, or
+  injection-token vocabulary to learn.
+
+See [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)'s
+`src/app_container.ks` and `src/routed_app.ks` for the real, working version this
+example is drawn from.
+
+## Structural directives
+
+Angular's `*ngIf`/`*ngFor`/`*ngSwitch` are template syntax that expands, at compile time,
+into imperative view-container calls. Kopular has no template compiler to expand
+anything into (`Render()` is already imperative — see `component.ks`), so there's no
+special syntax here either: each one maps onto a plain expression, and two of the three
+need nothing new at all.
+
+| Angular          | Kopular                                    | New code? |
+| ----------------- | ------------------------------------------- | :-------: |
+| `*ngFor`          | `array.ForEach((item) => ...)`              | none — already a KopScript array method |
+| `*ngSwitch`       | `match value { ... }`                       | none — already a KopScript expression, and exhaustiveness-checked (`*ngSwitch` isn't) |
+| `*ngIf` / `*ngIf-else` | `If(condition, () => ..., () => ...)`  | `directives.ks` |
+
+`*ngIf` is the one case that needs something new: `if` is a *statement* in KopScript, so
+without a helper you'd need a throwaway mutable local just to get a conditional value out
+of it. `If()` is that helper — nothing more than:
+
+```ks
+Element If(bool condition, () => Element whenTrue, () => Element whenFalse) {
+  if (condition) {
+    return whenTrue();
+  }
+  return whenFalse();
+}
+```
+
+Both branches are required (same reasoning `Router` uses for requiring a `NotFoundPage`
+up front — see `router.ks`): v1 has no nullable types, so "render nothing" has no value
+to hand back. Only the branch actually taken runs — the other lambda is never called, so
+an explicit empty branch (`() => document.createElement("span")`) costs nothing when
+there's genuinely nothing to show.
+
+All three read the same way, right inside `Render()` — no template file, no directive
+registration, nothing to import beyond the function itself:
+
+```ks
+public override Element Render() {
+  Element root = document.createElement("div");
+
+  // *ngIf
+  root.appendChild(If(this.User.IsLoggedIn, () => this.BuildProfile(), () => this.BuildLoginButton()));
+
+  // *ngFor
+  Element list = document.createElement("ul");
+  this.Items.ForEach((Item item) => { list.appendChild(this.BuildItemRow(item)); });
+  root.appendChild(list);
+
+  // *ngSwitch
+  root.appendChild(match this.Status {
+    "loading" => this.BuildSpinner(),
+    "error" => this.BuildError(),
+    _ => this.BuildContent()
+  });
+
+  return root;
+}
+```
 
-That's the whole framework — three files. Everything else (a real app built on top of
-it) lives in a separate consumer repo, [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo).
+Why not a general reuse-existing-DOM-nodes diffing layer, the way `*ngFor trackBy`
+avoids rebuilding unchanged rows? That needs comparing old and new *data* items by a
+caller-supplied key, generic over the item type — and KopScript has no generics (no
+`class Foo<T>`, no `T Resolve<T>()`). A one-off keyed-diff helper could be hand-written
+per list, but that's real vdom-diffing work — already called out as out of scope in
+"Status" below, and not something these three lines take on.
 
 ## Using Kopular from another KopScript project
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, and routing, with no template DSL and no DI container",
   "type": "module",
   "license": "MIT",
@@ -20,19 +20,22 @@
     ".": "./src/component.js",
     "./component": "./src/component.js",
     "./router": "./src/router.js",
-    "./dom": "./src/dom.js"
+    "./dom": "./src/dom.js",
+    "./directives": "./src/directives.js"
   },
   "files": [
-    "src"
+    "src",
+    "assets",
+    "LLM.md"
   ],
   "scripts": {
-    "build": "ks build src/router.ks",
+    "build": "ks build src/router.ks && ks build src/directives.ks",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "kopscript": "^0.1.0",
+    "kopscript": "^0.2.0",
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",

package/src/directives.js

@@ -0,0 +1,8 @@
+import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
+
+export function If(condition, whenTrue, whenFalse) {
+  if (condition) {
+    return whenTrue();
+  }
+  return whenFalse();
+}

package/src/directives.ks

@@ -0,0 +1,30 @@
+using "./dom";
+
+// Kopular's structural-directive equivalents — see the README's
+// "Structural directives" section for the full *ngIf/*ngFor/*ngSwitch
+// mapping. There's no template language here (Kopular doesn't have one, by
+// design — see component.ks), so these are just plain functions: call them
+// like any other expression from inside Render(), the same way you'd call
+// document.createElement.
+//
+// *ngFor and *ngSwitch need nothing new — `array.ForEach(...)` and
+// KopScript's own `match` expression already cover them (and `match` is
+// exhaustiveness-checked, which *ngSwitch isn't). `If` below is the one
+// piece the language doesn't already give you as an expression: `if` is a
+// statement in KopScript, so without this you'd need a throwaway mutable
+// local to get a conditional value.
+
+// The *ngIf equivalent — conditionally build one of two subtrees, as an
+// expression. Both branches are required: v1 has no nullable types, so
+// "render nothing" has no value to return — the same reasoning Router uses
+// for requiring a NotFoundPage up front (see router.ks) rather than letting
+// "no match" be null. Only the branch actually taken runs; the other
+// lambda is never called, so an explicit empty branch (e.g.
+// `() => document.createElement("span")`) costs nothing when there's
+// genuinely nothing to show.
+Element If(bool condition, () => Element whenTrue, () => Element whenFalse) {
+  if (condition) {
+    return whenTrue();
+  }
+  return whenFalse();
+}