kopular 0.23.1 → 1.0.0

package/LLM.md

@@ -9,10 +9,12 @@ not repeated here.
 Published as npm `kopular`. Entry points: `kopular` / `kopular/component` (Component),
 `kopular/velement` (VElement — what `Render()` returns; see "Component" below),
 `kopular/router` (Router), `kopular/dom` (ambient DOM bindings), `kopular/directives`
-(If), `kopular/http` (Http), `kopular/forms` (FormField, Validators), `kopular/testing`
-(runKopularApp, runKopularFixture — see below). `kopular/vdom` (the diff/patch engine
-behind `Update()`) is internal — nothing outside `component.ks` needs to import it
-directly. Also ships a bin, `kp` — `npx kp new
+(If), `kopular/http` (Http), `kopular/forms` (FormField, Validators), `kopular/computed`
+(Computed1, Computed2), `kopular/resource` (Resource, AsyncStatus), `kopular/vdom`
+(`ScopedStyles` — the runtime half of `styles from`; everything else in this file, the
+diff/patch engine behind `Update()`, is internal, nothing else here needs importing
+directly), `kopular/testing` (runKopularApp, runKopularFixture — see below). Also ships a
+bin, `kp` — `npx kp new
 <dir>` scaffolds a new project (the `extern` bindings below, plus the vendor/serve
 scripts needed to run in a browser) rather than requiring it be reconstructed by hand;
 prefer it over hand-writing the section below for a new project. Templates (`template
@@ -24,21 +26,22 @@ there is no `kopular/template` entry point to import.
 `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.
 
-**`Element`/`Document`/`Event` are NOT part of Kopular's own exports** — they're plain
-ambient browser globals (`extern class Element { ... };`, no `from` clause), genuinely
-present at runtime with no import needed, but Kopular has no re-exportable copy of them
-to reach for: `kopular/dom` is Kopular's own *internal* ambient binding, itself made of
-erased `extern` declarations with nothing real behind them at runtime, so `extern class
-Element { ... } from "kopular/dom";` doesn't work — there's no `Element` symbol actually
-living in that module to bind to. Every consuming project re-declares its own
-Element/Document/Event, same as this one does. **Copy the block below rather than
-hand-rolling a smaller one from scratch and adding members as compile errors demand
-them** — a real, complete first-attempt implementation of a Kopular app hit the exact
-same missing property (`Element.value`) twice from two independently-trimmed subsets,
-because the compile error only ever names the one member actually touched, never warns
-that a *sibling* feature (a template's `placeholder="..."` attribute, a `[(value)]`
-binding's generated `e.target.value` read) will need one you didn't happen to write by
-hand:
+**Don't reach for `Element`/`Document`/`Event` via `extern ... from "kopular/dom";`, even
+though that actually works** (`kopular/dom` genuinely re-exports real `globalThis`
+bindings, same as any other Kopular export) — **redeclare your own ambient block
+instead.** The reason isn't that importing wouldn't work; it's that Kopular's own internal
+`dom.ks` only declares what Kopular's own framework code itself touches, a smaller
+surface than a real app typically needs (`Element.value`/`.placeholder`, `.href`/`.src`/
+`.alt`, `.querySelector`, ...) — importing it would silently cap you at that subset with
+no signal you're missing something until you hit a real compile error for each one, one
+at a time. Every consuming project re-declares its own Element/Document/Event, same as
+this one does. **Copy the block below rather than hand-rolling a smaller one from scratch
+and adding members as compile errors demand them** — a real, complete first-attempt
+implementation of a Kopular app hit the exact same missing property (`Element.value`)
+twice from two independently-trimmed subsets, because the compile error only ever names
+the one member actually touched, never warns that a *sibling* feature (a template's
+`placeholder="..."` attribute, a `[(value)]` binding's generated `e.target.value` read)
+will need one you didn't happen to write by hand:
 
 ```ks
 extern class Event {
@@ -109,6 +112,10 @@ extern class VElement {
 extern class Component {
   constructor();
   virtual VElement Render();      // `virtual` here is what lets your subclass `override` it
+  // Renders a fallback UI instead of an uncaught crash if Render() throws
+  // — see "Component" below. Purely additive; not overriding it keeps
+  // today's exact (uncaught) behavior.
+  virtual VElement RenderError(string message);
   virtual void AfterRender(Element root); // see "Component" below
   void Mount(Element parent);
   void Update();
@@ -120,8 +127,26 @@ extern class Component {
 extern class Router {
   constructor(Component notFoundPage);
   void AddRoute(string path, Component page);
+  // Real code-splitting — see "Router" below. loader is a real dynamic
+  // import(), reached via a hand-written loader shim.
+  void AddLazyRoute(string path, () => task<Component> loader);
+  // Every registered path (AddRoute + AddLazyRoute), in registration
+  // order — see "Router" below.
+  string[] AllPaths();
   void Navigate(string path);
   void Mount(Element parent);
+  // One guard for the whole Router, not per-route — see "Router" below.
+  void SetGuard(string redirectPath, (string) => bool guard);
+  // The FIRST captured :name segment from whatever route just matched —
+  // "" if the matched route has no dynamic segment. Not state<T>; no
+  // Subscribe() needed — see "Common mistakes" below for why.
+  string Param { get; }
+  // Any captured :name segment (or a trailing * wildcard, as "*") by
+  // name, for a route with more than one — see "Router" below.
+  string Params(string name);
+  // A query-string value by key ("" if absent), independent of which
+  // route matched.
+  string Query(string key);
 } from "kopular/router";
 
 extern VElement If(bool condition, () => VElement whenTrue, () => VElement whenFalse) from "kopular/directives";
@@ -231,7 +256,11 @@ w.Bump();                // re-render + diff + patch
 - `VElement`: `Tag`, `TextContent`/`ClassName`/`Id`/`Value` (direct fields — `Value` is the
   one that must be a live DOM *property*, not an attribute: `SetAttr("value", x)` sets the
   default value, not the current one), `RawHtml` (an opaque, undiffed leaf — set instead of
-  `TextContent`/children, for a raw-HTML-then-wire-handlers pattern), the four fixed named
+  `TextContent`/children, for a raw-HTML-then-wire-handlers pattern — **sets real
+  `innerHTML`, unescaped: only ever assign static/developer-authored content — a `raw
+  string ... from "<path>.html";` compile-time constant, in every real use in this
+  ecosystem today — never anything reachable from user input, a fetched `Http` response
+  body, or a `FormField<T>`'s `.Value`, or it's a real XSS hole**), the four fixed named
   event fields `OnClick`/`OnInput`/`OnBlur`/`OnChange` (each a real no-op by default, never
   null — no nullable function type to fall back on), `AppendChild(child)`, and
   `SetAttr(name, value)` (the escape hatch for any other real HTML attribute — `href`,
@@ -370,6 +399,11 @@ class Counter : Component {
   `blur`/`change` — `VElement`'s own fixed set — anything else is a compile error
   (`KS5016`). `[prop]`/static `attr="..."` assign directly for `id`/`className`/`value`;
   anything else goes through `SetAttr` instead.
+- **`*mount="expr"`** embeds a live child Component declaratively — desugars to
+  `VElement.Mount(expr)`, the same mechanism a hand-written `Render()` uses (see "Nested
+  component composition" below). Unlike `*if`/`*for`, it composes with either — `*for="Row
+  r of Rows" *mount="r"` (one mounted child per loop item) is the headline case, not an
+  error. See kopscript's own `LLM.md`/`README.md` for the full syntax.
 - A `state<T>` field declared directly on the class and referenced directly in the
   template (`Count` above) gets `Subscribe((v) => this.Update())` wired automatically —
   no manual `Subscribe` in the constructor for that field. State reached indirectly
@@ -380,7 +414,8 @@ class Counter : Component {
   `this.Field` (see KopScript's own LLM.md `KS5017`/`KS5018` for the two rejected cases).
 - One top-level element per template (hard error otherwise); no mixing text and element
   children under one element (`VElement` has no text-node sibling concept, only
-  `.TextContent`); no pipes, at most one structural directive per element.
+  `.TextContent`); no pipes, at most one of `*if`/`*for` per element (`*mount` is
+  orthogonal to both — see above — and isn't included in that limit).
 - This is entirely a KopScript compiler feature (parsed/desugared before type-checking
   runs) — Kopular's own framework code (`component.ks`, `dom.ks`) is unmodified and
   unaware templates exist; a template-generated `Render()` is indistinguishable from a
@@ -708,10 +743,14 @@ try {
 Compiles `entryFileName` (plus everything else in `srcDir` it `using`s) via kopscript's
 `compileGraph`, binds jsdom onto `globalThis` (`document`/`Element`/`Event`/`location`/
 `history`/`window`/`fetch`) for the compiled ambient `extern` declarations to find, and
-runs it. Every `.ks`/`.html`/`.js` file in `srcDir` is copied along with it — `.js`
+runs it. Every `.ks`/`.html`/`.js`/`.css` file in `srcDir` is copied along with it — `.js`
 included specifically so a hand-written (not compiled) sibling like a `Router.AddLazyRoute`
-loader shim just works with no extra setup; `extraFiles` is only for a real dependency with
-some OTHER extension (e.g. a `.json` config file). `runKopularFixture(source, options)` is the sibling export for an inline fixture
+loader shim just works with no extra setup, `.css` the same way for a `styles from
+"<path>.css";` stylesheet; `extraFiles` is only for a real dependency with some OTHER
+extension (e.g. a `.json` config file). `runKopularFixture(source, options)` also takes
+an `options.extraSource` (`Record<string, string>` — filename to inline content) for
+supplying a fixture's own auxiliary `.html`/`.css` file without a real file on disk, since
+`runKopularFixture` only ever writes the one entry-file string you pass it. This is the sibling export for an inline fixture
 string instead of a real file (used by Kopular's own test suite; copies Kopular's *own*
 `.ks` sources alongside the fixture, so `using "./component"` resolves — only meaningful
 for testing Kopular itself, not an external consumer, which should use `runKopularApp`
@@ -769,6 +808,15 @@ class CounterService {
 
 ## Common mistakes (seeded from real generation failures)
 
+- **`VElement.RawHtml` sets real `innerHTML`, completely unescaped — never assign it
+  anything reachable from user input.** It exists for a raw-HTML-then-wire-a-delegated-
+  listener pattern (see `header.ks`/`nav.ks` in KopularDemo), and every real use in this
+  ecosystem is a `raw string ... from "<path>.html";` compile-time constant — genuinely
+  static content, baked in at build time, never a runtime value. There is nothing in the
+  type system stopping `el.RawHtml = someFetchedString;` or `el.RawHtml =
+  formField.Value.Value;` from compiling — both are a real XSS hole if that content is
+  ever attacker-influenced. Use `TextContent` (always escaped) for any dynamic string;
+  `RawHtml` is for static markup only.
 - **`Router.Param` is a plain `string`, not `state<T>` — don't `Subscribe()` to it.** A
   `state<T>`-based design for it was tried and genuinely crashes: `Navigate()` sets `Param`
   *before* the newly-matched page finishes mounting, so a page `Subscribe`-ing to it fires
@@ -819,13 +867,16 @@ imperative `Render()` code as the hand-written form, checked at compile time, no
 interpreted at runtime (see "Templates" above) · two-way binding in a hand-written
 `Render()`, or on anything but `value` even in a template (`[(value)]="Field"` exists —
 see "Templates" above — but it's `value`-only, and templates-only) ·
-embedding a child Component from a *template* (`.html`) — `VElement.Mount(component)`
-works only from a hand-written `Render()` today, see "Component" above ·
 a generic/arbitrary `VElement` event binding — only `click`/`input`/`blur`/`change` ·
 pipes · animations · typed/generic HTTP responses (`Http` returns raw text — see above) ·
-SSR.
-
-(`FormField<T>`/`Validators` and `kp new` — see "FormField<T> / Validators" and "Starting
-a new project" above — are real, shipped features; they used to be listed here as gaps
-before those landed and this list wasn't updated at the time. Leaving this parenthetical
-rather than quietly deleting it, as a reminder to keep this list in sync going forward.)
+live, per-request SSR — no framework-level renderer ships for this, but build-time static
+prerendering is a real, demonstrated pattern built entirely on existing pieces
+(`Router.AllPaths()` + `kopular/testing`'s `runKopularApp`, no Kopular framework code
+needed) — see KopularDemo's own `scripts/prerender.mjs`.
+
+(`FormField<T>`/`Validators`, `kp new`, and embedding a child Component from a *template*
+via `*mount="expr"` — see "FormField<T> / Validators", "Starting a new project", and
+"Nested component composition" above — are all real, shipped features; they used to be
+listed here as gaps before those landed and this list wasn't updated at the time. Leaving
+this parenthetical rather than quietly deleting it, as a reminder to keep this list in
+sync going forward.)

package/README.md

@@ -615,6 +615,26 @@ class Panel : Component {
 }
 ```
 
+## Raw HTML, and its real security boundary
+
+`VElement.RawHtml` sets a real, opaque `innerHTML` — an undiffed leaf, in place of
+`TextContent`/children, for a raw-markup-plus-one-delegated-listener pattern (this site's
+own `header.ks`/`nav.ks` use it exactly this way):
+
+```ks
+VElement header = VElement.Create("header");
+header.RawHtml = SiteHeaderHtml; // a raw string ... from "./header.html"; constant
+header.OnClick = (Event e) => { /* one delegated listener over the whole subtree */ };
+```
+
+**It's unescaped, real `innerHTML` — never assign it anything reachable from user input.**
+Every real use in this ecosystem is a `raw string ... from "<path>.html";` compile-time
+constant (see KopScript's own docs) — genuinely static markup, baked in at build time,
+never a runtime value. Nothing in the type system stops `el.RawHtml =
+someFetchedString;` or `el.RawHtml = formField.Value.Value;` from compiling — both are a
+real XSS hole if that content is ever attacker-influenced. Use `TextContent` (always
+escaped) for any dynamic string; `RawHtml` is for static markup only.
+
 ## HTTP
 
 ```ks
@@ -910,7 +930,9 @@ 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 KopScript
+`kopscript` is a real published dependency (see `package.json`'s own `devDependencies` for
+the exact version this repo currently requires — not restated by hand here, since it
+changes far more often than this paragraph does) — this repo doesn't need KopScript
 checked out as a sibling directory or anything else local to build or test.
 
 ## Status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.23.1",
+  "version": "1.0.0",
   "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"
   },