kopular 0.18.0 → 0.19.0

package/LLM.md

@@ -564,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

@@ -638,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.18.0",
+  "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); });
+  }
+}