kopular 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# Kopular
+
+Kopular is a small component framework for [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/Kop),
+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, no template DSL.
+
+## Highlights
+
+- **`Component`**: a base class with `virtual Render()` (builds a fresh DOM subtree from
+  current state) and `Update()` (swaps the old subtree for the new one). No template
+  language, no diffing — components build/update the DOM imperatively against plain DOM
+  bindings, the way you'd write careful vanilla-JS UI code.
+- **Reactive state, no RxJS**: components hold `state<number>`/`state<string>`/... (a
+  KopScript language feature — see the [Kop](https://dev.azure.com/koppinator/Koppindependence/_git/Kop)
+  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`**: hash-based (`#/path`, driven by the browser's native `hashchange` event)
+  page-swapping, with route registration as plain method calls, not a config DSL. No
+  server-side fallback route needed, unlike History-API routing.
+
+## What's here
+
+- `src/dom.ks` — ambient DOM bindings (`document`, `Element`, `Event`, `window`,
+  `location`) that `component.ks`/`router.ks` are built on.
+- `src/component.ks` — the `Component` base class.
+- `src/router.ks` — the `Router`.
+
+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).
+
+## 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:
+
+```ks
+extern class Component {
+  constructor();
+  virtual Element 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";
+
+class MyWidget : Component {
+  public override Element Render() {
+    Element el = document.createElement("div");
+    el.textContent = "Hello from MyWidget";
+    return el;
+  }
+}
+```
+
+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).
+
+## Getting started (developing Kopular itself)
+
+```bash
+npm install   # pulls in kopscript as a devDependency
+npm run build # compiles src/*.ks -> src/*.js (compiled output is gitignored)
+npm test      # runs test/kopular.test.ts against a real DOM via jsdom
+```
+
+`kopscript` is a real published dependency (`^0.1.0`) — this repo doesn't need Kop
+checked out as a sibling directory or anything else local to build or test.
+
+## Status
+
+v1 / hobby-project scope, same as KopScript itself. Known limitation: `Component` only
+handles a single component's own re-render cycle — if a *parent* re-renders while it has
+mounted children, those children aren't automatically re-mounted into the parent's new
+tree (real reconciliation, the way React/Vue handle this, is real vdom-diffing work well
+beyond v1). Compose independent components into stable slots (see `Router`'s own pattern
+of keeping page instances alive rather than rebuilding them) to avoid the issue.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "kopular",
+  "version": "0.1.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",
+  "author": "Joe Koppin <koppinjo@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/koppinator/Koppindependence/_git/Kopular"
+  },
+  "keywords": ["kopscript", "framework", "components", "ui"],
+  "main": "./src/component.js",
+  "exports": {
+    ".": "./src/component.js",
+    "./component": "./src/component.js",
+    "./router": "./src/router.js",
+    "./dom": "./src/dom.js"
+  },
+  "files": ["src"],
+  "scripts": {
+    "build": "ks build src/router.ks",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "kopscript": "^0.1.0",
+    "@types/jsdom": "^30.0.0",
+    "@types/node": "^20.14.0",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/component.js

@@ -0,0 +1,19 @@
+import { Event, Element, Document, Location, Window, document, location, window } from "./dom.js";
+
+export class Component {
+  Render() {
+    return document.createElement("div");
+  }
+
+  Mount(parent) {
+    (this.ParentElement = parent);
+    (this.Root = this.Render());
+    parent.appendChild(this.Root);
+  }
+
+  Update() {
+    let newRoot = this.Render();
+    this.ParentElement.replaceChild(newRoot, this.Root);
+    (this.Root = newRoot);
+  }
+}

package/src/component.ks

@@ -0,0 +1,35 @@
+using "./dom";
+
+// A minimal component base: subclasses override Render() to imperatively
+// build a fresh DOM tree from current state, and call the inherited
+// Update() whenever that state changes to swap the old tree for a new one.
+// There is deliberately no template language or diffing here — Render()
+// rebuilds its whole subtree every time, the simplest thing that works.
+//
+// Known limitation: if a *parent* component's own Render() re-runs (i.e.
+// something calls Update() on the parent) while it has mounted children,
+// those children are not automatically re-mounted into the parent's new
+// tree — this base class only handles a single component's own re-render
+// cycle, not parent/child reconciliation across one. Composing independent
+// components (each mounted into its own stable slot, as in app.kop) avoids
+// the issue entirely.
+class Component {
+  protected Element Root;
+  private Element ParentElement;
+
+  public virtual Element Render() {
+    return document.createElement("div");
+  }
+
+  public void Mount(Element parent) {
+    this.ParentElement = parent;
+    this.Root = this.Render();
+    parent.appendChild(this.Root);
+  }
+
+  protected void Update() {
+    Element newRoot = this.Render();
+    this.ParentElement.replaceChild(newRoot, this.Root);
+    this.Root = newRoot;
+  }
+}

package/src/dom.js

@@ -0,0 +1,8 @@
+export const Event = globalThis.Event;
+export const Element = globalThis.Element;
+export const Document = globalThis.Document;
+export const Location = globalThis.Location;
+export const Window = globalThis.Window;
+export const document = globalThis.document;
+export const location = globalThis.location;
+export const window = globalThis.window;

package/src/dom.ks

@@ -0,0 +1,39 @@
+// Minimal browser DOM bindings. All ambient (no `from` clause) — document,
+// Element, and Event genuinely exist as globals in a browser, no import
+// needed. Member names use the real JS casing exactly (camelCase), since
+// extern declarations describe an existing external contract rather than
+// idiomatic Kop code — there's no per-member rename mechanism. `extern
+// class` declarations end in `;`, like the other two extern forms.
+
+extern class Event {
+  Element target { get; }
+  void preventDefault();
+};
+
+extern class Element {
+  string textContent { get; set; }
+  string id { get; set; }
+  string className { get; set; }
+  void appendChild(Element child);
+  void replaceChild(Element newChild, Element oldChild);
+  void addEventListener(string eventType, (Event) => void handler);
+  void removeEventListener(string eventType, (Event) => void handler);
+};
+
+extern class Document {
+  Element createElement(string tagName);
+  Element getElementById(string id);
+  Element body { get; }
+};
+
+extern class Location {
+  string hash { get; set; }
+};
+
+extern class Window {
+  void addEventListener(string eventType, (Event) => void handler);
+};
+
+extern Document document;
+extern Location location;
+extern Window window;

package/src/router.js

@@ -0,0 +1,40 @@
+import { Event, Element, Document, Location, Window, document, location, window } from "./dom.js";
+import { Component } from "./component.js";
+
+export class Router extends Component {
+  constructor(notFoundPage) {
+    super();
+    (this.Paths = []);
+    (this.Pages = []);
+    (this.NotFoundPage = notFoundPage);
+    window.addEventListener("hashchange", (e) => (this.Update()));
+  }
+
+  AddRoute(path, page) {
+    (this.Paths = [...this.Paths, path]);
+    (this.Pages = [...this.Pages, page]);
+  }
+
+  Navigate(path) {
+    (location.hash = ("#" + path));
+  }
+
+  Match(path) {
+    let found = this.NotFoundPage;
+    for (let i = 0; (i < this.Paths.length); (i = (i + 1))) {
+      if ((this.Paths[i] === path)) {
+        (found = this.Pages[i]);
+      }
+    }
+    return found;
+  }
+
+  Render() {
+    let outlet = document.createElement("div");
+    (outlet.className = "router-outlet");
+    let path = location.hash.replaceAll("#", "");
+    let page = this.Match(path);
+    page.Mount(outlet);
+    return outlet;
+  }
+}

package/src/router.ks

@@ -0,0 +1,70 @@
+using "./dom";
+using "./component";
+
+// Hash-based routing (`#/path`, driven by the browser's native `hashchange`
+// event) rather than the History API — it needs no server-side fallback
+// (a plain static file server, like scripts/serve.mjs, has nothing special
+// to do for a hash), and there's no `pushState(state, title, url)` signature
+// to model through `extern`. Route registration is imperative (`AddRoute`
+// calls), not a config object — one thing to learn, not a routing DSL.
+//
+// Routes are registered as already-constructed Component instances, not
+// factories — `Component[]`, not `(() => Component)[]` (KopScript's type
+// grammar has no way to write "array of function type" in v1, since a
+// parenthesized function type isn't a general grouping construct). This
+// turns out to be a genuine feature, not just a workaround: each page
+// Component is built once and kept alive for the Router's own lifetime, so
+// a page's own state<T> fields survive navigating away and back — no state
+// gets reset just because a route wasn't showing for a while.
+//
+// No nullable types in v1 means "no route matched" can't be represented as
+// null — a `NotFoundPage` is required up front instead, the same way a
+// `match` expression requires its own `_` wildcard arm.
+class Router : Component {
+  private string[] Paths;
+  private Component[] Pages;
+  private Component NotFoundPage;
+
+  constructor(Component notFoundPage) : base() {
+    this.Paths = [];
+    this.Pages = [];
+    this.NotFoundPage = notFoundPage;
+    window.addEventListener("hashchange", (Event e) => this.Update());
+  }
+
+  public void AddRoute(string path, Component page) {
+    this.Paths = this.Paths.Push(path);
+    this.Pages = this.Pages.Push(page);
+  }
+
+  // Setting location.hash fires a real 'hashchange' event, which the
+  // constructor already subscribed to — no direct call to Update() needed
+  // here, the same "set the value, listeners react" shape as state<T>.
+  public void Navigate(string path) {
+    location.hash = "#" + path;
+  }
+
+  private Component Match(string path) {
+    Component found = this.NotFoundPage;
+    for (number i = 0; i < this.Paths.Length; i = i + 1) {
+      if (this.Paths[i] == path) {
+        found = this.Pages[i];
+      }
+    }
+    return found;
+  }
+
+  // Rebuilding a fresh outlet every render and re-Mount()ing the matched
+  // page into it means there's nothing to explicitly unmount: Update()
+  // (inherited from Component) discards the whole outlet in one
+  // replaceChild when it swaps in the new one. The page instance itself
+  // isn't rebuilt, just re-attached — see the class comment above.
+  public override Element Render() {
+    Element outlet = document.createElement("div");
+    outlet.className = "router-outlet";
+    string path = location.hash.Replace("#", "");
+    Component page = this.Match(path);
+    page.Mount(outlet);
+    return outlet;
+  }
+}