kopscript 0.16.0 → 0.18.0

package/LLM.md

@@ -540,11 +540,22 @@ class Counter : Component {
 - One `template` per class; a class with both `template` and a hand-written `Render()` is a
   compile error.
 - Desugars, between parsing and checking, into the exact same `MethodDecl` AST a
-  hand-written `Render()` would produce — no runtime template engine, no virtual DOM.
-  `{{ }}`/binding contents are real KopScript, parsed and type-checked normally.
-- Bindings: `{{ expr }}` (text interpolation, → `InterpolatedStringLiteral`), `(event)="stmt"`
-  (→ `addEventListener`), `[prop]="expr"` (→ plain assignment, checked like any member
-  assignment), static `attr="..."` (`class` aliases to `className`).
+  hand-written `Render()` would produce — building a `VElement` tree as data, no runtime
+  template engine, no diffing of its own (Kopular's own `Component` base class does that
+  against the tree this produces). `{{ }}`/binding contents are real KopScript, parsed and
+  type-checked normally.
+- Bindings: `{{ expr }}` (text interpolation, → `VElement.TextContent = InterpolatedStringLiteral`),
+  `(event)="stmt"` (→ assignment to one of `VElement`'s four named event fields —
+  `OnClick`/`OnInput`/`OnBlur`/`OnChange`; any other event name is a compile error),
+  `[prop]="expr"` (→ a plain field assignment for `id`/`className`/`value`, or
+  `VElement.SetAttr("prop", expr)` for anything else), static `attr="..."` (`class` aliases
+  to `className`).
+- **Two-way binding**: `[(value)]="Field"` → `[value]="Field"` + an auto-generated
+  `(input)="Field = e.target.value"`. `value` only (`KS5017` otherwise — no other
+  `VElement` field has an equivalent "user just changed this" event); `Field` must resolve
+  to a bare name or `this.Field` (`KS5018` otherwise — anything else has nothing sensible
+  to assign back into). A hand-written `Render()` has no equivalent shorthand — it already
+  has direct field/handler access, so there's nothing to desugar.
 - Structural directives: `*if="expr"` (→ real `if`), `*for="Type varName of expr"` (→ real
   `for..in`; the element type is explicit — no inference, same stance as Generics).
   At most one structural directive per element.
@@ -553,12 +564,12 @@ class Counter : Component {
   manual `Subscribe` needed for that field. State reached indirectly (through a method call,
   or `this.SomeService.Count`) still needs a manual `Subscribe`, unchanged from before.
 - Exactly one top-level element per template (no auto-wrap — hard error). No mixing text and
-  element children under one element. No two-way binding, no pipes, no stacked directives.
+  element children under one element. No pipes, no stacked directives.
 - `ks watch` tracks the referenced `.html` file as well as `.ks` dependencies.
 - Layering note: `template from` is kopscript grammar, but what it desugars *to*
-  (`document.createElement`/`.appendChild`/`.textContent`/`.addEventListener`) assumes
-  Kopular's `dom.ks` DOM surface specifically — a deliberate, documented coupling, not a
-  generic pluggable target.
+  (`VElement.Create`/`.AppendChild`/`.TextContent`/`.SetAttr`/the named `On*` event fields)
+  assumes Kopular's `velement.ks` surface specifically — a deliberate, documented coupling,
+  not a generic pluggable target.
 
 ## Keywords (reserved, lowercase, exact match)
 

package/README.md

@@ -538,12 +538,12 @@ class Counter : Component {
     this.Count.Subscribe((number v) => this.Update());
   }
 
-  public override Element Render() {
-    Element button = document.createElement("button");
-    button.textContent = "Count: " + this.Count.Value;
-    button.addEventListener("click", (Event e) => {
+  public override VElement Render() {
+    VElement button = VElement.Create("button");
+    button.TextContent = "Count: " + this.Count.Value;
+    button.OnClick = (Event e) => {
       this.Count.Value = this.Count.Value + 1; // Update() fires automatically
-    });
+    };
     return button;
   }
 }
@@ -587,11 +587,13 @@ class Counter : Component {
 This compiles to exactly the `Render()` method you'd otherwise write by hand — the
 template compiler is a pass that runs between parsing and type-checking, turning the
 markup into ordinary `MethodDecl`/statement/expression AST nodes and splicing the result
-into the class before checking ever runs. There's no separate runtime template engine, no
-virtual DOM diffing, and no interpreted expression language: `{{ Count.Value }}` and
-`(click)="Increment()"` contain real KopScript, parsed and type-checked exactly like
-anything else in the file, with errors reported at their real position in the `.html`
-file, not the `.ks` file.
+into the class before checking ever runs. There's no separate runtime template engine and
+no interpreted expression language: `{{ Count.Value }}` and `(click)="Increment()"`
+contain real KopScript, parsed and type-checked exactly like anything else in the file,
+with errors reported at their real position in the `.html` file, not the `.ks` file. The
+compiler itself does no diffing — it just builds a `VElement` tree as data; Kopular's own
+`Component` base class is what diffs that tree against the previous render and patches
+real DOM (see Kopular's own README/CHANGELOG for that engine).
 
 A class may have a `template` or a hand-written `Render()`, never both — that's a compile
 error. `ks watch` also tracks the referenced `.html` file, so editing markup alone
@@ -601,13 +603,25 @@ Supported bindings and directives:
 
 | Syntax                      | Desugars to                                              |
 | --------------------------- | --------------------------------------------------------- |
-| `{{ expr }}` (in text)       | `el.textContent = $"...{expr}...";` (an `InterpolatedStringLiteral`, same as `$"..."`) |
-| `(event)="stmt"`             | `el.addEventListener("event", (Event e) => { stmt });`   |
-| `[prop]="expr"`              | `el.prop = expr;` — a plain assignment, checked like any other |
-| `class="..."` (static)       | `el.className = "...";` (aliased, since `class` is a KopScript keyword) |
+| `{{ expr }}` (in text)       | `el.TextContent = $"...{expr}...";` (an `InterpolatedStringLiteral`, same as `$"..."`) |
+| `(event)="stmt"`             | `el.OnEvent = (Event e) => { stmt };` — `event` must be one of `click`/`input`/`blur`/`change`, `VElement`'s own fixed set of named event fields |
+| `[prop]="expr"`              | `el.Prop = expr;` for `id`/`className`/`value` (`VElement`'s own named fields); `el.SetAttr("prop", expr);` for anything else |
+| `[(value)]="Field"`          | sugar for `[value]="Field"` + `(input)="Field = e.target.value"` — see below |
+| `class="..."` (static)       | `el.ClassName = "...";` (aliased, since `class` is a KopScript keyword) |
 | `*if="expr"`                 | a real `if (expr) { ... }` around the element's creation |
 | `*for="Type var of expr"`    | a real `for (Type var in expr) { ... }` — the element type is explicit, matching KopScript's no-inference stance elsewhere (Generics, Nullable types) |
 
+**Two-way binding**: `[(value)]="Field"` (a template-only sugar — there's no equivalent
+shorthand for a hand-written `Render()`, which already has direct field/handler access)
+desugars to exactly the pair you'd otherwise write by hand: a `[value]` property binding
+plus an auto-generated `(input)` handler assigning back. Restricted to `value`
+specifically — the one `VElement` field a user can change through direct interaction
+(typing, picking an option); `[(id)]`/`[(className)]` are compile errors (`KS5017`), since
+neither has an equivalent "user just changed this" event. The bound expression must be a
+simple field reference (a bare name or `this.Field`, resolving the same way any other
+binding does) — `[(value)]="Field.Trim()"` is a compile error (`KS5018`), since there's
+nothing sensible to assign back into.
+
 **Auto-subscribe**: a `state<T>` field declared directly on the component and referenced
 directly in its template (like `Count` above) gets its `Subscribe((v) => this.Update())`
 wired up automatically — no manual `Subscribe` call needed in the constructor. This is a
@@ -618,14 +632,15 @@ templates existed.
 
 v1 cuts, same discipline as generics and nullable types: exactly one top-level element per
 template (no auto-wrapping — a clear error instead); no mixing text and element children
-under one element (Kopular's DOM surface has no text-node type, only `.textContent`); no
-two-way binding, no pipes, no stacking two structural directives on one element.
+under one element (`VElement` has no text-node concept, only `.TextContent`); no pipes, no
+stacking two structural directives on one element.
 
 **A deliberate layering note**: the `template from` syntax lives in kopscript's own
 grammar (Kopular can't extend a language it doesn't own), but what it desugars *to* —
-`document.createElement`, `.appendChild`, `.textContent`, `.addEventListener` — assumes
-exactly the DOM surface [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)'s
-`dom.ks` declares. That's a real coupling from the compiler to one specific consumer,
+`VElement.Create`, `.AppendChild`, `.TextContent`, `.SetAttr`, the named `On*` event
+fields — assumes exactly the surface
+[Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)'s
+`velement.ks` declares. That's a real coupling from the compiler to one specific consumer,
 accepted deliberately rather than building a generic pluggable desugaring-target system
 for a hypothetical second framework that doesn't exist today. If one ever does, that's the
 point to generalize this.

package/dist/template_compiler.js

@@ -1,6 +1,16 @@
-const ELEMENT_TYPE = { kind: "NamedType", name: "Element", typeArgs: null, line: 0, col: 0 };
+const VELEMENT_TYPE = { kind: "NamedType", name: "VElement", typeArgs: null, line: 0, col: 0 };
 const VOID_TYPE = { kind: "NamedType", name: "void", typeArgs: null, line: 0, col: 0 };
 const EVENT_TYPE = { kind: "NamedType", name: "Event", typeArgs: null, line: 0, col: 0 };
+// The only attrs/prop bindings with a real named VElement field — anything
+// else goes through SetAttr instead (see buildAttrAssignment). Keys are
+// post-alias names (see template_parser.ts's PROPERTY_ALIASES — "class" is
+// already "className" by the time it reaches here).
+const KNOWN_FIELD_NAMES = { id: "Id", className: "ClassName", value: "Value" };
+// VElement's own fixed, named event slots (see velement.ks) — there's no
+// generic addEventListener on VElement (event handlers are part of the
+// VNode's own data, not wired against a live DOM node), so a template can
+// only bind one of these four.
+const KNOWN_EVENT_NAMES = { click: "OnClick", input: "OnInput", blur: "OnBlur", change: "OnChange" };
 function ident(name, at) {
     return { kind: "Identifier", name, line: at.line, col: at.col };
 }
@@ -20,7 +30,7 @@ function assign(target, value, at) {
     return exprStatement({ kind: "AssignExpr", target, value, line: at.line, col: at.col }, at);
 }
 function varDecl(name, init, at) {
-    return { kind: "VarDecl", isConst: false, name, nameLine: at.line, nameCol: at.col, type: ELEMENT_TYPE, init, line: at.line, col: at.col };
+    return { kind: "VarDecl", isConst: false, name, nameLine: at.line, nameCol: at.col, type: VELEMENT_TYPE, init, line: at.line, col: at.col };
 }
 function block(statements, at) {
     return { kind: "Block", statements, line: at.line, col: at.col };
@@ -181,7 +191,7 @@ export class TemplateCompiler {
             nameLine: templateDeclAt.line,
             nameCol: templateDeclAt.col,
             params: [],
-            returnType: ELEMENT_TYPE,
+            returnType: VELEMENT_TYPE,
             body: block(statements, templateDeclAt),
             line: templateDeclAt.line,
             col: templateDeclAt.col,
@@ -200,14 +210,19 @@ export class TemplateCompiler {
         const varName = this.freshVar();
         const statements = [];
         const self = ident(varName, at);
-        statements.push(varDecl(varName, call(member(ident("document", at), "createElement", at), [stringLiteral(node.tag, at)], at), at));
+        statements.push(varDecl(varName, call(member(ident("VElement", at), "Create", at), [stringLiteral(node.tag, at)], at), at));
         for (const attr of node.staticAttrs)
-            statements.push(assign(member(self, attr.name, attr), stringLiteral(attr.value, attr), attr));
+            statements.push(this.buildAttrAssignment(self, attr.name, stringLiteral(attr.value, attr), attr));
         for (const bind of node.propBindings) {
             const value = this.resolve(bind.value, localScope);
-            statements.push(assign(member(self, bind.name, bind), value, bind));
+            statements.push(this.buildAttrAssignment(self, bind.name, value, bind));
         }
         for (const bind of node.eventBindings) {
+            const fieldName = KNOWN_EVENT_NAMES[bind.name];
+            if (!fieldName) {
+                this.diagnostics.error("KS5016", `Unsupported event binding '(${bind.name})' — a template can only bind (click), (input), (blur), or (change), the same fixed set of named event fields VElement itself has`, bind.line, bind.col);
+                continue;
+            }
             const handler = this.resolve(bind.handler, localScope);
             const handlerParam = { name: "e", type: EVENT_TYPE };
             const lambda = {
@@ -217,8 +232,10 @@ export class TemplateCompiler {
                 line: bind.line,
                 col: bind.col,
             };
-            statements.push(exprStatement(call(member(self, "addEventListener", bind), [stringLiteral(bind.name, bind), lambda], bind), bind));
+            statements.push(assign(member(self, fieldName, bind), lambda, bind));
         }
+        for (const bind of node.twoWayBindings)
+            statements.push(...this.buildTwoWayBinding(self, bind, localScope));
         const elementChildren = node.children.filter((c) => c.kind === "element");
         const textChildren = node.children.filter((c) => c.kind === "text");
         if (textChildren.length > 0 && elementChildren.length > 0) {
@@ -227,7 +244,7 @@ export class TemplateCompiler {
         else if (textChildren.length > 0) {
             const parts = textChildren.flatMap((t) => t.parts).map((p) => (p.kind === "Expr" ? { kind: "Expr", expression: this.resolve(p.expression, localScope) } : p));
             const interpolated = { kind: "InterpolatedStringLiteral", parts, line: at.line, col: at.col };
-            statements.push(assign(member(self, "textContent", at), interpolated, at));
+            statements.push(assign(member(self, "TextContent", at), interpolated, at));
         }
         else {
             for (const child of elementChildren)
@@ -271,6 +288,49 @@ export class TemplateCompiler {
         return [...statements, this.appendChild(parentVar, elVar, node)];
     }
     appendChild(parentVar, childVar, at) {
-        return exprStatement(call(member(ident(parentVar, at), "appendChild", at), [ident(childVar, at)], at), at);
+        return exprStatement(call(member(ident(parentVar, at), "AppendChild", at), [ident(childVar, at)], at), at);
+    }
+    // A known name (post-alias — "class" already reads "className" by here)
+    // becomes a direct assignment to VElement's own named field; anything
+    // else — href, src, alt, placeholder, ... — goes through VElement.SetAttr
+    // instead, under its original, real HTML attribute name (SetAttr's own
+    // name argument is exactly what gets passed to a real setAttribute call
+    // at patch time — see vdom.ks).
+    buildAttrAssignment(self, name, value, at) {
+        const fieldName = KNOWN_FIELD_NAMES[name];
+        if (fieldName) {
+            return assign(member(self, fieldName, at), value, at);
+        }
+        return exprStatement(call(member(self, "SetAttr", at), [stringLiteral(name, at), value], at), at);
+    }
+    // `[(value)]="Field"` desugars to exactly the two-piece pattern you'd
+    // otherwise write by hand — `[value]="Field"` (a plain property binding)
+    // plus `(input)="Field = e.target.value"` (an auto-generated handler
+    // assigning back). Restricted to `value` specifically: it's the one
+    // VElement field a user can change through direct interaction (typing,
+    // picking an option) with no event of Kopular's own in between — `id`/
+    // `className` have no equivalent "user just changed this" event, so
+    // there's nothing for a two-way binding to mean for them.
+    buildTwoWayBinding(self, bind, localScope) {
+        if (bind.name !== "value") {
+            this.diagnostics.error("KS5017", `Unsupported two-way binding '[(${bind.name})]' — only [(value)] is supported, the one VElement field a user can change through direct interaction`, bind.line, bind.col);
+            return [];
+        }
+        const target = this.resolve(bind.target, localScope);
+        if (target.kind !== "Identifier" && target.kind !== "MemberExpr") {
+            this.diagnostics.error("KS5018", `A two-way binding target must be a simple field reference (a bare name or 'this.Field'), not a complex expression`, bind.line, bind.col);
+            return [];
+        }
+        const propAssign = this.buildAttrAssignment(self, bind.name, target, bind);
+        const assignBack = assign(target, member(member(ident("e", bind), "target", bind), "value", bind), bind);
+        const lambda = {
+            kind: "LambdaExpr",
+            params: [{ name: "e", type: EVENT_TYPE }],
+            body: block([assignBack], bind),
+            line: bind.line,
+            col: bind.col,
+        };
+        const eventAssign = assign(member(self, "OnInput", bind), lambda, bind);
+        return [propAssign, eventAssign];
     }
 }

package/dist/template_parser.js

@@ -162,6 +162,7 @@ export class TemplateParser {
         const staticAttrs = [];
         const propBindings = [];
         const eventBindings = [];
+        const twoWayBindings = [];
         let ifCondition = null;
         let forBinding = null;
         while (this.check(TemplateTokenKind.AttrName)) {
@@ -171,7 +172,15 @@ export class TemplateParser {
             if (!valueTok)
                 continue;
             const name = nameTok.lexeme;
-            if (name.startsWith("(") && name.endsWith(")")) {
+            // Checked before the plain `[prop]` case below — `[(value)]` also
+            // starts with `[` and ends with `]`, so it would otherwise be
+            // mistaken for a property binding named literally "(value)".
+            if (name.startsWith("[(") && name.endsWith(")]")) {
+                const propName = name.slice(2, -2);
+                const target = this.parseEmbeddedExpression(valueTok.lexeme, valueTok.line, valueTok.col);
+                twoWayBindings.push({ name: propName, target, line: nameTok.line, col: nameTok.col });
+            }
+            else if (name.startsWith("(") && name.endsWith(")")) {
                 const eventName = name.slice(1, -1);
                 const handler = this.parseEmbeddedExpression(valueTok.lexeme, valueTok.line, valueTok.col);
                 eventBindings.push({ name: eventName, handler, line: nameTok.line, col: nameTok.col });
@@ -226,7 +235,7 @@ export class TemplateParser {
                 this.diagnostics.error("KS5012", `Expected closing tag '</${tag}>'`, tagTok.line, tagTok.col);
             }
         }
-        return { kind: "element", tag, staticAttrs, propBindings, eventBindings, ifCondition, forBinding, children, line: tagTok.line, col: tagTok.col };
+        return { kind: "element", tag, staticAttrs, propBindings, eventBindings, twoWayBindings, ifCondition, forBinding, children, line: tagTok.line, col: tagTok.col };
     }
     consumeEquals(attrNameTok) {
         this.consume(TemplateTokenKind.Equals, attrNameTok, `Expected '=' after attribute '${attrNameTok.lexeme}'`);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "kopscript",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript, with generics and nullable types",
   "type": "module",
   "license": "MIT",
   "author": "Joe Koppin <koppinjo@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "https://dev.azure.com/koppinator/Koppindependence/_git/Kop"
+    "url": "https://dev.azure.com/koppinator/Koppindependence/_git/KopScript"
   },
   "homepage": "https://kopular.dev",
   "keywords": [