kopular 0.1.0 → 0.2.0

package/README.md

@@ -19,9 +19,11 @@ dependency-injection container, no template DSL.
   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.
+- **`Router`**: real URLs (`/about`, not `#/about`) via the History API
+  (`pushState`/`popstate`), with route registration as plain method calls, not a config
+  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`.
 
 ## What's here
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -9,7 +9,12 @@
     "type": "git",
     "url": "https://dev.azure.com/koppinator/Koppindependence/_git/Kopular"
   },
-  "keywords": ["kopscript", "framework", "components", "ui"],
+  "keywords": [
+    "kopscript",
+    "framework",
+    "components",
+    "ui"
+  ],
   "main": "./src/component.js",
   "exports": {
     ".": "./src/component.js",
@@ -17,7 +22,9 @@
     "./router": "./src/router.js",
     "./dom": "./src/dom.js"
   },
-  "files": ["src"],
+  "files": [
+    "src"
+  ],
   "scripts": {
     "build": "ks build src/router.ks",
     "prepublishOnly": "npm run build",

package/src/component.js

@@ -1,4 +1,4 @@
-import { Event, Element, Document, Location, Window, document, location, window } from "./dom.js";
+import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
 
 export class Component {
   Render() {

package/src/dom.js

@@ -2,7 +2,9 @@ export const Event = globalThis.Event;
 export const Element = globalThis.Element;
 export const Document = globalThis.Document;
 export const Location = globalThis.Location;
+export const History = globalThis.History;
 export const Window = globalThis.Window;
 export const document = globalThis.document;
 export const location = globalThis.location;
+export const history = globalThis.history;
 export const window = globalThis.window;

package/src/dom.ks

@@ -27,7 +27,13 @@ extern class Document {
 };
 
 extern class Location {
-  string hash { get; set; }
+  string pathname { get; }
+};
+
+extern class History {
+  // Param named `historyState`, not `state` — `state` is a KopScript
+  // keyword (state<T>), not a valid parameter name.
+  void pushState(string historyState, string title, string url);
 };
 
 extern class Window {
@@ -36,4 +42,5 @@ extern class Window {
 
 extern Document document;
 extern Location location;
+extern History history;
 extern Window window;

package/src/router.js

@@ -1,4 +1,4 @@
-import { Event, Element, Document, Location, Window, document, location, window } from "./dom.js";
+import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
 import { Component } from "./component.js";
 
 export class Router extends Component {
@@ -7,7 +7,7 @@ export class Router extends Component {
     (this.Paths = []);
     (this.Pages = []);
     (this.NotFoundPage = notFoundPage);
-    window.addEventListener("hashchange", (e) => (this.Update()));
+    window.addEventListener("popstate", (e) => (this.Update()));
   }
 
   AddRoute(path, page) {
@@ -16,7 +16,8 @@ export class Router extends Component {
   }
 
   Navigate(path) {
-    (location.hash = ("#" + path));
+    history.pushState("", "", path);
+    this.Update();
   }
 
   Match(path) {
@@ -32,7 +33,7 @@ export class Router extends Component {
   Render() {
     let outlet = document.createElement("div");
     (outlet.className = "router-outlet");
-    let path = location.hash.replaceAll("#", "");
+    let path = location.pathname;
     let page = this.Match(path);
     page.Mount(outlet);
     return outlet;

package/src/router.ks

@@ -1,12 +1,15 @@
 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.
+// History-API routing (real paths — `/about`, not `#/about`) via
+// `history.pushState`/the browser's native `popstate` event. This needs a
+// server that falls back to the app shell for any path it doesn't
+// recognize as a real file (see KopularDemo's scripts/serve.mjs) — a plain
+// static file server has nothing to serve at `/about` on a direct
+// visit/refresh otherwise, unlike hash-based routing, which never leaves
+// the one HTML file the server actually has. 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
@@ -29,7 +32,12 @@ class Router : Component {
     this.Paths = [];
     this.Pages = [];
     this.NotFoundPage = notFoundPage;
-    window.addEventListener("hashchange", (Event e) => this.Update());
+    // 'popstate' only fires on browser back/forward (or history.go/back/
+    // forward) — never on pushState itself, unlike hashchange firing
+    // whenever location.hash is set. Navigate() below calls Update()
+    // directly for that reason; this listener only covers the back/forward
+    // case, where the URL changes without any of our own code running.
+    window.addEventListener("popstate", (Event e) => this.Update());
   }
 
   public void AddRoute(string path, Component page) {
@@ -37,11 +45,9 @@ class Router : Component {
     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;
+    history.pushState("", "", path);
+    this.Update();
   }
 
   private Component Match(string path) {
@@ -62,7 +68,7 @@ class Router : Component {
   public override Element Render() {
     Element outlet = document.createElement("div");
     outlet.className = "router-outlet";
-    string path = location.hash.Replace("#", "");
+    string path = location.pathname;
     Component page = this.Match(path);
     page.Mount(outlet);
     return outlet;