kopular 0.23.2 → 1.0.1

package/LLM.md

@@ -109,6 +109,14 @@ extern class VElement {
   static VElement Mount(Component component);
 } from "kopular/velement";
 
+// Only needed if you use `styles from "./x.css";` in a class body (see
+// "Scoped styles" below) — the compiler splices a call to this into the
+// constructor automatically, but (like every other Kopular export) it
+// still needs its own `extern` declaration; it is NOT auto-imported.
+extern class ScopedStyles {
+  static void Inject(string id, string css);
+} from "kopular/vdom";
+
 extern class Component {
   constructor();
   virtual VElement Render();      // `virtual` here is what lets your subclass `override` it
@@ -133,6 +141,11 @@ extern class Router {
   // Every registered path (AddRoute + AddLazyRoute), in registration
   // order — see "Router" below.
   string[] AllPaths();
+  // Overridable outlet content shown while an AddLazyRoute page's loader
+  // is in flight — default: `<div class="router-loading">Loading...</div>`.
+  // Only declare this if you actually override it (a class extending
+  // Router) — see "Lazy routes" below.
+  protected virtual VElement BuildLoadingPlaceholder();
   void Navigate(string path);
   void Mount(Element parent);
   // One guard for the whole Router, not per-route — see "Router" below.
@@ -317,6 +330,11 @@ w.Bump();                // re-render + diff + patch
     return ul;
   }
   ```
+  `item.Id` above means exactly what it looks like: for a keyed list of mounted children,
+  the mounted `Component` itself needs its own public `Id` (or similarly-named) field/
+  property to copy onto `slot.Id` — `VElement.Id` lives on the wrapper slot, not on the
+  component, so there's nothing to key by without one. Set it however suits the type
+  (constructor param, or a plain field assigned right after construction).
   The SAME `Mountable` instance still in a slot across a re-render is patched in place
   (`Update()` inside that child re-renders just its own subtree, siblings untouched); a
   DIFFERENT instance (or the slot disappearing) tears the old one down first — calling its
@@ -434,7 +452,11 @@ class Widget : Component {
 - Independent of `template from` — works with a hand-written `Render()` too. The compiler
   rewrites the referenced `.css` so every selector requires a per-class
   `data-kop-scope="<id>"` attribute, then splices one `ScopedStyles.Inject(id, css);` call
-  into the constructor. **Unlike `template from`, this needed real framework code**:
+  into the constructor. **This means `ScopedStyles` must be `extern`-declared in your own
+  project the same as `Component`/`VElement`/etc. (see the copy-paste block above) — it is
+  NOT auto-imported just because you wrote `styles from`.** Forgetting it is a real `KS4048
+  Undefined identifier 'ScopedStyles'` at the constructor the compiler spliced the call
+  into. **Unlike `template from`, this needed real framework code**:
   `ScopedStyles` (`vdom.ks`, new) — idempotent, static-array-registry dedup shape same as
   `Batching`, injects one real `<style>` per component *type* (not per instance) into
   `document.head` (`dom.ks`'s `head { get; }`, new) the first time any instance is
@@ -532,10 +554,29 @@ nav.Navigate("/about");                          // pushState + immediate re-ren
   extern task<Component> LoadDogsPage() from "./dogs_page_loader";
   nav.AddLazyRoute("/dogs", LoadDogsPage);
   ```
-  The outlet shows a plain loading placeholder (override `BuildLoadingPlaceholder()`) while
-  the fetch is in flight; the loaded page is cached after the first fetch, same as an eager
-  page — navigating away and back reuses it, no re-fetch. Mixes freely with `AddRoute` in
-  the same `Router`.
+  The outlet shows a plain loading placeholder (`<div class="router-loading">Loading...</div>`
+  by default; override `protected virtual VElement BuildLoadingPlaceholder()` on a class
+  extending `Router` to customize) while the fetch is in flight; the loaded page is cached
+  after the first fetch, same as an eager page — navigating away and back reuses it, no
+  re-fetch. Mixes freely with `AddRoute` in the same `Router`.
+  - **Building it for real**: the whole point of a lazy route is that `dogs_page.ks` is
+    deliberately *not* `using`'d from your app's own entry file — that's what keeps its
+    code out of the eager bundle. That also means your normal build command (`ks build
+    src/app.ks`) never compiles it, since `ks build`/`compileGraph` only walk the `using`
+    graph reachable from the entry you give them. Build the lazy page as its own separate
+    entry too, e.g. `ks build src/app.ks && ks build src/dogs_page.ks` in your build
+    script (or one `ks build` invocation per lazy route, if you have several) — each
+    already-compiled shared dependency just gets written again with identical output, so
+    this is safe to add without restructuring anything else.
+  - **Testing it**: `kopular/testing`'s `runKopularApp` (kopular 0.24.0+) compiles any
+    other real `.ks` file present in your app's own `srcDir` that the entry doesn't
+    reach — a lazy-route target is exactly that — so a test exercising `AddLazyRoute`
+    needs no special setup: write `dogs_page.ks`/`dogs_page_loader.js` into the same
+    directory as your entry file, same as any other page, and the loader's
+    `import("./dogs_page.js")` finds a real, freshly-compiled file. (`runKopularFixture`,
+    used only by Kopular's own internal test suite, does not do this — it copies
+    Kopular's entire framework source tree alongside a fixture, where the same behavior
+    would mean recompiling most of the framework on every test.)
 - **`AllPaths(): string[]`** — every registered path (`AddRoute` + `AddLazyRoute`), in
   registration order. For enumerating real routes (a build-time prerender step, most
   likely) without a second, hand-maintained list.

package/README.md

@@ -166,8 +166,13 @@ class Widget : Component {
 ```
 
 Unlike `template from`, this **did** need real framework code — `ScopedStyles.Inject`
-(`vdom.ks`) is the runtime half: idempotent, injects one real `<style>` per component
-*type* into `document.head` the first time any instance of that type is constructed
+(`vdom.ks`) is the runtime half, and (like every other Kopular export) it needs its own
+`extern` declaration in your project — `extern class ScopedStyles { static void
+Inject(string id, string css); } from "kopular/vdom";` — it is not auto-imported just
+because you wrote `styles from`; omitting it is a real `KS4048 Undefined identifier
+'ScopedStyles'` at the constructor the compiler spliced the call into. It's idempotent,
+injecting one real `<style>` per component *type* into `document.head` the first time any
+instance of that type is constructed
 (dedup is per-type, not per-instance — every instance's constructor calls `Inject` with
 the same compile-time `id`/rewritten-`css`, so only the first actually creates a tag).
 Never removed once injected — a scoped stylesheet is global infrastructure for as long as
@@ -368,11 +373,23 @@ export async function LoadDogsPage() {
 extern task<Component> LoadDogsPage() from "./dogs_page_loader";
 ```
 
-The outlet shows a plain loading placeholder (override `BuildLoadingPlaceholder()` to
-customize it) while the fetch is in flight, then the real page once it resolves — and,
-like an eager page, it's only ever fetched once: navigating away and back reuses the same
-already-loaded instance, keeping whatever state it built up. A lazy and an eager route mix
-freely in the same `Router`; nothing about `AddRoute`'s own existing signature changes.
+The outlet shows a plain loading placeholder (`<div class="router-loading">Loading...</div>`
+by default; override `protected virtual VElement BuildLoadingPlaceholder()` on a class
+extending `Router` to customize it) while the fetch is in flight, then the real page once
+it resolves — and, like an eager page, it's only ever fetched once: navigating away and
+back reuses the same already-loaded instance, keeping whatever state it built up. A lazy
+and an eager route mix freely in the same `Router`; nothing about `AddRoute`'s own existing
+signature changes.
+
+**Building and testing a lazy route**: `dogs_page.ks` is deliberately *not* `using`'d from
+your app's own entry — that's what keeps it out of the eager bundle — which also means your
+normal `ks build src/app.ks` never compiles it, since `ks build` only walks the `using`
+graph reachable from the entry you give it. Build it as its own separate entry too:
+`ks build src/app.ks && ks build src/dogs_page.ks` (already-compiled shared dependencies
+just get written again with identical output, so this is safe to add). For tests,
+`kopular/testing`'s `runKopularApp` (0.24.0+) compiles any other real `.ks` file present in
+your `srcDir` that the entry doesn't reach — a lazy-route target is exactly that — so
+`AddLazyRoute` needs no special test setup at all.
 
 **`AllPaths()`** returns every registered path (both `AddRoute` and `AddLazyRoute`), in
 registration order — for a caller that needs to enumerate real routes (a build-time static

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.23.2",
+  "version": "1.0.1",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, real compiled templates, and HTTP, with no DI container",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",
-    "kopscript": "^0.26.0",
+    "kopscript": "^1.0.0",
     "typescript": "^5.5.0",
     "vitest": "^4.1.11"
   },

package/src/testing.js

@@ -111,19 +111,52 @@ function copyKopularPackage(dir) {
 // Shared by both exports below: compiles `entryFileName` (already written
 // into `dir`, alongside everything it `using`s) and runs it against a fresh
 // jsdom instance.
+//
+// `compileOrphanEntries` additionally compiles any other real `.ks` file
+// present in `dir` that the entry's own `using` graph never reaches. A
+// `Router.AddLazyRoute` target is *exactly* that by construction — it's
+// deliberately kept out of the eager `using` graph so its own JS is only
+// fetched on first navigation (see kopular's own LLM.md "Lazy routes"
+// section) — so without this, its loader shim's `await import("./x.js")`
+// finds nothing on disk here, even though the exact same app builds and
+// runs fine in a real browser (there, the app's own build script is
+// expected to invoke `ks build` on the lazy page too, as its own separate
+// entry point — see the same docs section). Only `runKopularApp` passes
+// this: `runKopularFixture` copies Kopular's *entire* framework source
+// tree alongside a small fixture, where "every .ks file the fixture
+// doesn't reach" would mean recompiling most of the framework on every
+// test.
 async function compileAndRun(dir, entryFileName, options) {
   const entry = join(dir, entryFileName);
-  const result = compileGraph(entry);
-  if (!result.success) {
+  const graphs = [compileGraph(entry)];
+
+  if (options.compileOrphanEntries) {
+    const covered = new Set(graphs[0].outputs.keys());
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".ks")) continue;
+      const absPath = join(dir, name);
+      if (absPath === entry || covered.has(absPath)) continue;
+      const g = compileGraph(absPath);
+      for (const p of g.outputs.keys()) covered.add(p);
+      graphs.push(g);
+    }
+  }
+
+  const failed = graphs.filter((g) => !g.success);
+  if (failed.length > 0) {
     rmSync(dir, { recursive: true, force: true });
-    const messages = [...result.modules.values()]
-      .filter((m) => m.diagnostics.hasErrors)
+    const seen = new Set();
+    const messages = failed
+      .flatMap((g) => [...g.modules.values()])
+      .filter((m) => m.diagnostics.hasErrors && !seen.has(m.absPath) && seen.add(m.absPath))
       .map((m) => m.diagnostics.format(m.source, m.absPath))
       .join("\n\n");
     throw new Error(messages || "Compilation failed");
   }
-  for (const [absPath, js] of result.outputs) {
-    writeFileSync(absPath.replace(/\.ks$/, ".js"), js, "utf-8");
+  for (const g of graphs) {
+    for (const [absPath, js] of g.outputs) {
+      writeFileSync(absPath.replace(/\.ks$/, ".js"), js, "utf-8");
+    }
   }
 
   const dom = new JSDOM("<!doctype html><html><body></body></html>", { url: options.url ?? "http://localhost/" });
@@ -162,6 +195,11 @@ async function compileAndRun(dir, entryFileName, options) {
  * real project's own src/ directory, the way KopularDemo's test suite (or
  * any app consuming `kopular/...` via `extern`) would use it.
  *
+ * Also compiles any other `.ks` file in `srcDir` the entry's `using` graph
+ * doesn't reach — a `Router.AddLazyRoute` target is exactly that, by
+ * design, so its loader shim's `import("./x.js")` finds a real file here
+ * too, with no extra setup needed to test a lazy route.
+ *
  * @param {string} srcDir - directory containing the entry file and
  *   everything it `using`s.
  * @param {string} entryFileName - the entry .ks file's name within srcDir.
@@ -186,7 +224,7 @@ export async function runKopularApp(srcDir, entryFileName, options = {}) {
   const dir = mkTempDir();
   copySources(srcDir, dir, options.extraFiles ?? []);
   if (options.includeKopularPackage) copyKopularPackage(dir);
-  return compileAndRun(dir, entryFileName, options);
+  return compileAndRun(dir, entryFileName, { ...options, compileOrphanEntries: true });
 }
 
 /**