kopular 0.17.2 → 0.19.0

package/LLM.md

@@ -284,6 +284,23 @@ w.Bump();                // re-render + diff + patch
     components, a modal that comes and goes.
   - Hand-written `Render()` only — there's no template (`.html`) syntax yet for embedding a
     child component the way `*if`/`*for` embed structural logic.
+- **Content projection (React's `children`/Angular's `<ng-content>`) needs no separate
+  mechanism** — pass a `() => VElement` into a child's constructor and call it from inside
+  its own `Render()`; it's invoked fresh every render and closes over the parent's `this`,
+  so projected content reflects the parent's current state on every patch:
+  ```ks
+  class Card : Component {
+    private () => VElement ContentBuilder;
+    constructor(() => VElement contentBuilder) : base() { this.ContentBuilder = contentBuilder; }
+    public override VElement Render() {
+      VElement div = VElement.Create("div");
+      div.AppendChild(this.ContentBuilder());
+      return div;
+    }
+  }
+  ```
+  More than one slot: one named `() => VElement` callback per slot (same fixed-named-slot
+  convention as `VElement`'s own `OnClick`/etc.), not a generic bag.
 - **`Update()` before `Mount()` is a safe no-op**, not an error. This matters for two
   sibling `Component`s (e.g. two `Router` pages) that share one injected service's
   `state<T>` and both `Subscribe()` it — every route's page is constructed eagerly (see
@@ -547,6 +564,26 @@ via `.Touch()` on `OnBlur`. A **template** has real `[(value)]="Field"` sugar fo
 value-binding half (see "Templates" above); `Touch()` on blur still needs its own explicit
 `(blur)="Field.Touch()"` either way — `[(value)]` only ever wires `value`/`input`.
 
+## `Computed1<A, R>` / `Computed2<A, B, R>` (`computed.ks`)
+
+```ks
+state<number> price = state(10);
+state<number> qty = state(2);
+Computed2<number, number, number> total = new Computed2<number, number, number>(
+  price, qty, (number p, number q) => p * q);
+
+total.Value.Value              // 20 — recomputed whenever price OR qty changes
+total.Value.Subscribe((number v) => { ... });  // returns an unsubscribe handle, same as any state<T>
+```
+
+`useMemo`/Angular signals' `computed()` equivalent — built entirely on `state<T>`'s own
+`.Value`/`.Subscribe`, no new reactive primitive. `Value` is `state<R>`, not a bare `R` —
+KopScript's property grammar has no custom-getter syntax, so a computed value can't expose
+a self-recomputing property; `state<R>` already gives the right two members instead.
+Dependencies are explicit constructor arguments, not automatically tracked. Fixed arity (1
+source, 2 sources) — same array-of-function-values reason `CombineValidators2/3` are fixed;
+add a `Computed3<A, B, C, R>` the same way if ever needed.
+
 ## `kopular/testing` (`testing.js`, hand-written JS, not compiled from `.ks`)
 
 ```ts

package/README.md

@@ -468,6 +468,65 @@ removal to get right, so there's nothing this mechanism would add there. Reach f
 `VElement.Mount` for anything with real add/remove/reorder: a list of components, a modal
 that comes and goes, anything genuinely dynamic.
 
+## Content projection — a parent giving a child what to render
+
+React's `children` prop and Angular's `<ng-content>` both let a parent hand a child
+arbitrary markup to render at a spot the child itself decides. Kopular needs no separate
+mechanism for this at all: pass a `() => VElement` into the child's constructor, the same
+as any other constructor argument, and have the child call it from inside its own
+`Render()`:
+
+```ks
+class Card : Component {
+  private () => VElement ContentBuilder;
+  constructor(() => VElement contentBuilder) : base() {
+    this.ContentBuilder = contentBuilder;
+  }
+  public override VElement Render() {
+    VElement div = VElement.Create("div");
+    div.ClassName = "card";
+    div.AppendChild(this.ContentBuilder());
+    return div;
+  }
+}
+
+// Usage — the parent decides what's inside the card, Card decides the chrome around it:
+Card card = new Card(() => this.BuildCardBody());
+```
+
+Because the callback is invoked fresh on every one of `Card`'s own renders (not a value
+captured once and frozen), and it's a closure over the *parent's* own `this`, the projected
+content reflects the parent's current state every time — bump a field the parent's own
+`BuildCardBody()` reads, call the parent's `Update()`, and `Card`'s own next patch shows the
+new value, patched in place like any other content. No new API: this is just
+`VElement.Mount` plus an ordinary function-typed constructor argument, the same "no hidden
+magic, explicit constructor args" pattern dependency injection above already uses.
+
+More than one projection point works the same way — one named callback per slot, the same
+fixed-named-slot convention `VElement`'s own `OnClick`/`OnInput`/`OnBlur`/`OnChange` already
+use rather than a generic, unordered bag:
+
+```ks
+class Panel : Component {
+  private () => VElement HeaderBuilder;
+  private () => VElement BodyBuilder;
+  constructor(() => VElement headerBuilder, () => VElement bodyBuilder) : base() {
+    this.HeaderBuilder = headerBuilder;
+    this.BodyBuilder = bodyBuilder;
+  }
+  public override VElement Render() {
+    VElement div = VElement.Create("div");
+    VElement header = VElement.Create("header");
+    header.AppendChild(this.HeaderBuilder());
+    div.AppendChild(header);
+    VElement body = VElement.Create("section");
+    body.AppendChild(this.BodyBuilder());
+    div.AppendChild(body);
+    return div;
+  }
+}
+```
+
 ## HTTP
 
 ```ks
@@ -579,6 +638,42 @@ gets real sugar for exactly this — `[(value)]="Field"` desugars to `[value]="F
 `(input)="Field = e.target.value"` (see KopScript's own "Templates" docs) — since a
 markup file has no equivalent direct access to fall back on.
 
+## Computed values
+
+React's `useMemo`/Angular signals' `computed()` equivalent — a read-only value derived
+from one or more `state<T>` sources, recomputed and re-notified whenever a source changes:
+
+```ks
+using "./computed";
+
+state<number> price = state(10);
+state<number> qty = state(2);
+Computed2<number, number, number> total = new Computed2<number, number, number>(
+  price, qty, (number p, number q) => p * q);
+
+print(total.Value.Value);              // 20
+total.Value.Subscribe((number v) => print("total: " + v));
+price.Value = 15;                      // prints "total: 30"
+```
+
+`Value` is `state<R>`, not a bare `R` — KopScript's property grammar has no custom-getter
+syntax (only auto-implemented `{ get; }`/`{ get; set; }`), so a computed value can't expose
+a property that recomputes itself on read. `state<R>` already **is** the right shape for
+"read the current value, or subscribe to it changing" — `total.Value.Value`/
+`total.Value.Subscribe(...)` are the exact same two members any other `state<T>` has, not a
+parallel API to learn.
+
+Dependencies are explicit, not automatically tracked the way Angular signals infer their
+own by watching which signals get read during evaluation — that needs a live "currently
+evaluating" context threaded through every read, a different kind of feature from anything
+else here. Naming each source directly is one honest step short of automatic, consistent
+with explicit constructor arguments everywhere else in Kopular (dependency injection,
+routing). `Computed1<A, R>` covers one source; `Computed2<A, B, R>` covers two — fixed
+arity for the same reason `CombineValidators2`/`CombineValidators3` (above) are: KopScript
+has no array-of-function-values type, and no way to express "N sources of N different
+types" without one type parameter per source. Add a `Computed3<A, B, C, R>` the same way if
+a real derivation ever needs three.
+
 ## Starting a new project: `kp new`
 
 Everything in the next section — the `extern` bindings, plus a `vendor/kopular/` copy of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.17.2",
+  "version": "0.19.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",
@@ -33,6 +33,7 @@
     "./directives": "./src/directives.js",
     "./http": "./src/http.js",
     "./forms": "./src/forms.js",
+    "./computed": "./src/computed.js",
     "./testing": "./src/testing.js"
   },
   "files": [
@@ -42,7 +43,7 @@
     "LLM.md"
   ],
   "scripts": {
-    "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks && ks build src/forms.ks",
+    "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks && ks build src/forms.ks && ks build src/computed.ks",
     "prepublishOnly": "npm run build",
     "pretest": "npm run build",
     "test": "vitest run",

package/src/computed.js

@@ -0,0 +1,37 @@
+class __KopState {
+  constructor(value) {
+    this._value = value;
+    this._listeners = [];
+  }
+  get Value() { return this._value; }
+  set Value(v) {
+    this._value = v;
+    for (const listener of this._listeners) listener(v);
+  }
+  Subscribe(listener) {
+    this._listeners.push(listener);
+    return () => { this._listeners = this._listeners.filter((l) => l !== listener); };
+  }
+}
+
+export class Computed1 {
+  constructor(source, compute) {
+    this.Value = new __KopState(compute(source.Value));
+    source.Subscribe((v) => {
+  this.Value.Value = compute(v);
+});
+  }
+}
+export class Computed2 {
+  constructor(a, b, compute) {
+    this.Value = new __KopState(compute(a.Value, b.Value));
+    a.Subscribe((v) => {
+  this.Value.Value = compute(v, b.Value);
+});
+    b.Subscribe((v) => {
+  this.Value.Value = compute(a.Value, v);
+});
+  }
+}
+
+//# sourceMappingURL=computed.js.map

package/src/computed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.js","sources":["computed.ks"],"sourcesContent":["// Computed1<A, R>/Computed2<A, B, R>: a read-only reactive value derived\n// from one or more state<T> sources, recomputed and re-notified whenever\n// any source changes — React's useMemo/Angular signals' computed()\n// equivalent. No new reactive primitive: built entirely on state<T>'s\n// existing .Value/.Subscribe (including the unsubscribe handle Subscribe\n// now returns — see kopscript's own LLM.md), the same way FormField<T>\n// (forms.ks) is built on state<T> rather than introducing a second\n// reactive system.\n//\n// Deliberately EXPLICIT dependencies, not automatic tracking (the way\n// Angular signals' computed() infers its own deps by watching which\n// signals get read during evaluation) — that needs a live \"currently\n// evaluating\" context the compiler/runtime would have to thread through\n// every read, a different kind of feature than anything else here.\n// Naming each source explicitly is one honest step short of automatic,\n// consistent with this project's own \"explicit constructor args, no\n// hidden magic\" position elsewhere (dependency injection, routing).\n//\n// `Value` is `state<R>`, not a bare `R` — KopScript's declared-property\n// grammar has no way to write a custom getter body (only auto-implemented\n// `{ get; }`/`{ get; set; }`, backed by ordinary assignment), so a\n// Computed can't expose a property that recomputes itself on read. state<R>\n// already IS the \"read the current value, or subscribe to it changing\"\n// shape this needs — Value.Value / Value.Subscribe(...), the exact same\n// two members any other state<T> exposes, not a parallel API to learn.\n//\n// Fixed arity (1 and 2 sources) for the same reason CombineValidators2/3\n// (forms.ks) are fixed-arity, not a general array-taking form: KopScript\n// has no array-of-function-values type, and no way to express \"N sources\n// of N different types\" without one type parameter per source. Add\n// Computed3<A, B, C, R> the same way if a real derivation ever needs three.\nclass Computed1<A, R> {\n  public state<R> Value { get; }\n\n  constructor(state<A> source, (A) => R compute) {\n    this.Value = state(compute(source.Value));\n    source.Subscribe((A v) => { this.Value.Value = compute(v); });\n  }\n}\n\nclass Computed2<A, B, R> {\n  public state<R> Value { get; }\n\n  constructor(state<A> a, state<B> b, (A, B) => R compute) {\n    this.Value = state(compute(a.Value, b.Value));\n    a.Subscribe((A v) => { this.Value.Value = compute(v, b.Value); });\n    b.Subscribe((B v) => { this.Value.Value = compute(a.Value, v); });\n  }\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;AA+BA;EAGE;IACa;IACK;EAA6B;;;;AAIjD;EAGE;IACa;IACA;EAA6B;;IAC7B;EAA6B"}

package/src/computed.ks

@@ -0,0 +1,49 @@
+// Computed1<A, R>/Computed2<A, B, R>: a read-only reactive value derived
+// from one or more state<T> sources, recomputed and re-notified whenever
+// any source changes — React's useMemo/Angular signals' computed()
+// equivalent. No new reactive primitive: built entirely on state<T>'s
+// existing .Value/.Subscribe (including the unsubscribe handle Subscribe
+// now returns — see kopscript's own LLM.md), the same way FormField<T>
+// (forms.ks) is built on state<T> rather than introducing a second
+// reactive system.
+//
+// Deliberately EXPLICIT dependencies, not automatic tracking (the way
+// Angular signals' computed() infers its own deps by watching which
+// signals get read during evaluation) — that needs a live "currently
+// evaluating" context the compiler/runtime would have to thread through
+// every read, a different kind of feature than anything else here.
+// Naming each source explicitly is one honest step short of automatic,
+// consistent with this project's own "explicit constructor args, no
+// hidden magic" position elsewhere (dependency injection, routing).
+//
+// `Value` is `state<R>`, not a bare `R` — KopScript's declared-property
+// grammar has no way to write a custom getter body (only auto-implemented
+// `{ get; }`/`{ get; set; }`, backed by ordinary assignment), so a
+// Computed can't expose a property that recomputes itself on read. state<R>
+// already IS the "read the current value, or subscribe to it changing"
+// shape this needs — Value.Value / Value.Subscribe(...), the exact same
+// two members any other state<T> exposes, not a parallel API to learn.
+//
+// Fixed arity (1 and 2 sources) for the same reason CombineValidators2/3
+// (forms.ks) are fixed-arity, not a general array-taking form: KopScript
+// has no array-of-function-values type, and no way to express "N sources
+// of N different types" without one type parameter per source. Add
+// Computed3<A, B, C, R> the same way if a real derivation ever needs three.
+class Computed1<A, R> {
+  public state<R> Value { get; }
+
+  constructor(state<A> source, (A) => R compute) {
+    this.Value = state(compute(source.Value));
+    source.Subscribe((A v) => { this.Value.Value = compute(v); });
+  }
+}
+
+class Computed2<A, B, R> {
+  public state<R> Value { get; }
+
+  constructor(state<A> a, state<B> b, (A, B) => R compute) {
+    this.Value = state(compute(a.Value, b.Value));
+    a.Subscribe((A v) => { this.Value.Value = compute(v, b.Value); });
+    b.Subscribe((B v) => { this.Value.Value = compute(a.Value, v); });
+  }
+}