# Kopular Kopular is a small component framework for [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/KopScript), built to give Angular's separation of concerns — components own UI, services own logic, a router owns navigation — without Angular's steepest learning-curve pieces: no RxJS, no dependency-injection container, and templates that are real, compiled, type-checked KopScript rather than a separate interpreted template language. 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`, with real vdom diffing**: a base class with `virtual Render()` (describes the current state as a `VElement` tree — a lightweight description of a DOM element, not a real one) and `Update()` (diffs the new tree against the previous one and patches only what changed, reusing a real DOM node wherever its tag stays the same — not a full subtree rebuild). `Render()` is provided as a real, separate markup file compiled by KopScript's `template from` (see "Templates" below), or written by hand building a `VElement` tree against `kopular/velement`, the way you'd write careful vanilla-JS UI code — your choice, and both compile to the exact same thing. An optional `virtual RenderError(message)` renders a fallback instead of a hard crash if `Render()` throws — purely additive; not overriding it keeps today's exact (uncaught) behavior. Every real DOM event handler Kopular attaches (`OnClick`/`OnInput`/`OnBlur`/`OnChange`) batches the `Update()` calls made while it runs into one render per component, applied once the handler returns, fully synchronously — a click handler that mutates more than one field only ever renders once, reading every field's final value, regardless of which statement happens to trigger it. See `LLM.md`'s "Component" section for the full rationale and the real bug this closes. - **Templates, compiled and type-checked, not interpreted**: markup lives in its own `.html` file — interpolation (`{{ }}`), event/property bindings (`(click)="..."`, `[prop]="..."`), and `*if`/`*for` structural directives — desugared by the KopScript compiler into the exact same code a hand-written `Render()` would produce, with automatic `Subscribe`/`Update()` wiring for `state` fields referenced directly in the markup. See "Templates" below. - **Reactive state, no RxJS**: components hold `state`/`state`/... (a KopScript language feature — see the [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/KopScript) repo) and subscribe once, in their constructor, to call `Update()` on change. No Observables, no operators, no manual unsubscribe bookkeeping. - **Services, no DI container**: "injecting" a service is just passing it as a constructor argument. No injector hierarchy, no provider tokens, no decorators — and a service stays fully testable with zero `Component`/DOM involvement, since it's just a class. - **`Router`**: real URLs (`/about`, not `#/about`) via the History API (`pushState`/`popstate`), with route registration as plain method calls, not a config DSL. See "Router, and deploying it" below — every deployment target needs its own SPA-fallback config, not just local dev. - **Structural directives**: `*ngIf`/`*ngFor`/`*ngSwitch`'s job — build a subtree conditionally, repeat one per item, pick one of several cases. In a template, that's `*if`/`*for` (real `if`/`for` under the hood — see "Templates"); in a hand-written `Render()`, the same job is a plain function call (`If(...)`) or existing KopScript expression (`array.ForEach(...)`, `match`) — no special syntax needed there either way. See "Structural directives" below. - **`Http`**: a thin, static wrapper over the real Fetch API (`Http.Get(url)`, `Http.Post(url, jsonBody)`, ...) — no HttpClient injection tokens, no RxJS observables/operators. See "HTTP" below. - **`FormField`**: a single input's value/error/touched state, built on `state` — no two-way-binding magic, no `FormGroup` config object. See "Forms" below. ## What's here - `src/dom.ks` — ambient DOM bindings (`document`, `Element`, `Event`, `window`, `location`) that `component.ks`/`router.ks`/`directives.ks` are built on. - `src/velement.ks` — `VElement`, the lightweight description of a DOM element `Render()` returns. - `src/vdom.ks` — the diff/patch engine (`Materialize`/`Patch`/`PatchChildren`) behind real vdom diffing — see "Component" above. - `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). - `src/http.ks` — `Http`, a thin wrapper over `fetch` (see below). `src/http_runtime.js` is its one companion file — the single hand-written (not compiled from `.ks`) file in Kopular, and why is explained in its own header comment. - `src/forms.ks` — `FormField` and `Validators` (see "Forms" below). - `src/testing.js` — `runKopularApp`/`runKopularFixture` (see "Testing your own app" below); hand-written for the same reason as `http_runtime.js` — filesystem/process orchestration isn't a Kopular `Component`. - `bin/kp.mjs` — the `kp new` scaffolding CLI (see "Starting a new project" below); also hand-written, same reason. That's the whole framework — ten files, plus the scaffolding CLI. 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). ## Templates A component's `Render()` can be a real markup file instead of hand-written imperative DOM code — `template from "./x.html";` in the class body, a KopScript language feature (see [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/KopScript)'s own README/LLM.md for the full syntax reference). Kopular itself needed **zero framework code changes** for this — the compiler desugars a template straight into calls against the same `VElement.Create`/`.AppendChild`/`.TextContent`/named event fields `velement.ks` already declares, so a template-generated `Render()` is indistinguishable from one you'd write by hand: ```ks // counter.ks class Counter : Component { public state Count; constructor() : base() { this.Count = state(0); } public void Increment() { this.Count.Value = this.Count.Value + 1; } template from "./counter.html"; } ``` ```html Count: {{ Count.Value }} ``` Note there's no `this.Count.Subscribe(...)` anywhere — a `state` field referenced directly in the template (`Count.Value` above) gets it wired automatically. The exact same component, hand-written, needs that `Subscribe` call itself: ```ks class Counter : Component { private state Count; constructor() : base() { this.Count = state(0); this.Count.Subscribe((number v) => this.Update()); } public override VElement Render() { VElement button = VElement.Create("button"); button.TextContent = "Count: " + this.Count.Value; button.OnClick = (Event e) => { this.Count.Value = this.Count.Value + 1; }; return button; } } ``` Both produce the same `Render()`, and can be mixed freely across a codebase — nothing about `Component`, `Update()`, or any other Kopular API differs between them. The manual `Subscribe` call is still exactly what you need the moment state is reached *indirectly* — through a method call, or through an injected service's own state (`this.Service.Count`, say) — which is why the real, production `Counter` on the [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) site (it injects a `CounterService` rather than holding `Count` itself) uses a template but still has one manual `Subscribe`. `*if`/`*for` in a template are covered under "Structural directives" below, alongside their hand-written-`Render()` equivalents. ## Scoped component styles A class-body `styles from "./x.css";` — also a KopScript language feature (see [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/KopScript)'s own README/LLM.md for the full syntax/CSS-parsing reference) — scopes a real stylesheet so it only matches elements *that class itself* renders, never a sibling's or a child's: ```ks class Widget : Component { constructor() : base() { } template from "./widget.html"; styles from "./widget.css"; } ``` ```css /* widget.css */ .title { color: royalblue; } ``` Unlike `template from`, this **did** need real framework code — `ScopedStyles.Inject` (`vdom.ks`) is the runtime half, and `using "kopular";` brings it in along with everything else — do **not** write your own `extern class ScopedStyles ... from "kopular/vdom";`, which is now a real `KS4002 Declaration 'ScopedStyles' conflicts with a name brought in by 'using'`. (Before package `using` existed, every Kopular export did need a hand-written `extern` in your project; that is what `using "kopular";` replaced.) It's idempotent, injecting one real `