kopular 1.1.4 → 1.2.0

package/GUIDE.md

@@ -43,6 +43,8 @@ both scripts). `ks check src/app.ks` type-checks without building, if you just w
 - `try { } catch (string e) { } finally { }` and `throw "message";` all exist — one `catch`
   per `try`, and its parameter type is your choice (it is *not* checked against what was
   actually thrown).
+- **Comments are `//` only** — there is no `/* ... */` block comment, and a `/*` is a parse
+  error (`KS2020`), not an ignored region.
 - **Reserved words**: naming a local or parameter one of these is a parse error, not
   shadowing — `raw`, `state`, `task`, `from`, `as`, `get`, `set`, `in`, `base` and `match`
   are the ones easy to pick by accident. Full list: `using extern raw template styles from
@@ -57,6 +59,9 @@ both scripts). `ks check src/app.ks` type-checks without building, if you just w
   `.Split(sep)`, `.Replace(from, to)`, `.CompareTo(other)` (sort comparator), `+` concatenates.
   Both `"double"` and `'single'` quotes work — use whichever the other isn't, e.g. inside
   a template attribute (`*if="Name != ''"`).
+- Arrays are created with a literal and nothing else: `number[] xs = [];`, `[1, 2, 3]`,
+  `[new Todo("a")]`. **There is no `new number[3]` form** — that's a parse error, not an
+  empty array.
 - Arrays: `xs.Length`, `.Map()/.Filter()/.ForEach()/.Find()/.FindIndex()/.Includes()/.IndexOf()`,
   `.Sort(cmp)/.Reverse()/.Push(x)` (all three **non-mutating**, return a new array),
   `.Slice(a, b)/.Concat(ys)/.Join(sep)/.Reduce(fn, initial)`.

package/LLM.md

@@ -135,10 +135,10 @@ 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.
+// The runtime half of `styles from "./x.css";` (see "Scoped styles" below)
+// — the compiler splices a call to this into the constructor. Listed here
+// for reference: `using "kopular";` already brings it in, and declaring it
+// yourself on top of that is a real KS4002 conflict.
 extern class ScopedStyles {
   static void Inject(string id, string css);
 } from "kopular/vdom";
@@ -171,7 +171,7 @@ extern class Router {
   // 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();
+  virtual VElement BuildLoadingPlaceholder();
   void Navigate(string path);
   void Mount(Element parent);
   // One guard for the whole Router, not per-route — see "Router" below.
@@ -320,6 +320,7 @@ w.Bump();                // re-render + diff + patch
   component, applied once the handler returns:
   ```ks
   private void Save() {
+    Item newItem = new Item(this.Draft);      // whatever this handler just built
     this.Draft = "";                          // a plain field Render() also reads
     this.Items.Value = this.Items.Value.Push(newItem);  // triggers the ONE render, via Subscribe
   }
@@ -503,7 +504,7 @@ Real URLs via the History API (`pushState`/`popstate`), not hash routing.
 
 ```ks
 class NotFoundPage : Component {
-  public override VElement Render() { /* ... */ }
+  public override VElement Render() { return VElement.Create("h1"); }
 }
 class HomePage : Component {
   private Router Nav;

package/README.md

@@ -166,11 +166,11 @@ class Widget : Component {
 ```
 
 Unlike `template from`, this **did** need real framework code — `ScopedStyles.Inject`
-(`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,
+(`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 `<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
@@ -595,8 +595,17 @@ class Card : Component {
   }
 }
 
-// Usage — the parent decides what's inside the card, Card decides the chrome around it:
-Card card = new Card(() => this.BuildCardBody());
+// Usage, from inside the parent's own Render() — the parent decides what's inside the
+// card, Card decides the chrome around it. `this` only means anything in a method, so
+// that is where the callback is built:
+class Page : Component {
+  constructor() : base() { }
+  public override VElement Render() {
+    Card card = new Card(() => this.BuildCardBody());
+    return VElement.Mount(card);
+  }
+  private VElement BuildCardBody() { return VElement.Create("p"); }
+}
 ```
 
 Because the callback is invoked fresh on every one of `Card`'s own renders (not a value
@@ -641,7 +650,7 @@ 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 */ };
+header.OnClick = (Event e) => { };  // one delegated listener over the whole subtree
 ```
 
 **It's unescaped, real `innerHTML` — never assign it anything reachable from user input.**
@@ -655,7 +664,7 @@ escaped) for any dynamic string; `RawHtml` is for static markup only.
 ## HTTP
 
 ```ks
-using "./http";
+using "kopular";
 
 Response r = await Http.Get("/api/dogs");
 if (r.ok) {
@@ -706,7 +715,7 @@ else avoids the problem by only wrapping JS APIs that take plain positional argu
 ## Forms
 
 ```ks
-using "./forms";
+using "kopular";
 
 FormField<string> email = new FormField<string>("", (string v) => {
   string? required = Validators.Required(v);
@@ -719,6 +728,7 @@ print(email.Error.Value);   // "Must be a valid email"
 print(email.Valid());       // false
 
 // inside a hand-written Render(), building emailInput as a VElement:
+VElement emailInput = VElement.Create("input");
 emailInput.OnInput = (Event e) => {
   email.Value.Value = e.target.value;   // revalidates automatically
 };
@@ -769,7 +779,7 @@ React's `useMemo`/Angular signals' `computed()` equivalent — a read-only value
 from one or more `state<T>` sources, recomputed and re-notified whenever a source changes:
 
 ```ks
-using "./computed";
+using "kopular";
 
 state<number> price = state(10);
 state<number> qty = state(2);
@@ -806,18 +816,23 @@ commonly wrapping an `Http` call — as reactive `state<T>` a `Component` can re
 `Subscribe` to, instead of hand-rolling the same three fields and try/catch every time:
 
 ```ks
-using "./resource";
+using "kopular";
 
-Resource<Response> dogs = new Resource<Response>(Http.Get("https://dog.ceo/api/breeds/list/all"));
-dogs.Status.Subscribe((AsyncStatus s) => this.Update());
+class DogsPage : Component {
+  private Resource<Response> dogs;
+  constructor() : base() {
+    this.dogs = new Resource<Response>(Http.Get("https://dog.ceo/api/breeds/list/all"));
+    this.dogs.Status.Subscribe((AsyncStatus s) => this.Update());
+  }
+}
 ```
 
 ```ks
 public override VElement Render() {
-  return match dogs.Status.Value {
+  return match this.dogs.Status.Value {
     AsyncStatus.Loading => this.BuildSpinner(),
-    AsyncStatus.Success => this.BuildList(dogs.Data.Value),
-    AsyncStatus.Failure => this.BuildError(dogs.Error.Value)
+    AsyncStatus.Success => this.BuildList(this.dogs.Data.Value),
+    AsyncStatus.Failure => this.BuildError(this.dogs.Error.Value)
   };
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "1.1.4",
+  "version": "1.2.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",

package/src/kopular.ks

@@ -156,6 +156,12 @@ extern class Validators {
   static string? Max(number value, number max);
 } from "kopular/forms";
 
+// Chain validators into the single (T) => string? a FormField takes. Real
+// generic free functions in forms.ks; without these declared here, a
+// consumer using `using "kopular";` couldn't reach them at all.
+extern (T) => string? CombineValidators2<T>((T) => string? v1, (T) => string? v2) from "kopular/forms";
+extern (T) => string? CombineValidators3<T>((T) => string? v1, (T) => string? v2, (T) => string? v3) from "kopular/forms";
+
 extern class Computed1<A, R> {
   constructor(state<A> source, (A) => R compute);
   state<R> Value { get; }