kopscript 0.16.0 → 0.17.0

package/LLM.md

@@ -540,11 +540,16 @@ 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`).
 - 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.
@@ -556,9 +561,9 @@ class Counter : Component {
   element children under one element. No two-way binding, 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,10 +603,10 @@ 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 |
+| `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) |
 
@@ -623,9 +625,10 @@ two-way binding, 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,7 +232,7 @@ 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));
         }
         const elementChildren = node.children.filter((c) => c.kind === "element");
         const textChildren = node.children.filter((c) => c.kind === "text");
@@ -227,7 +242,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 +286,19 @@ 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);
     }
 }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "kopscript",
-  "version": "0.16.0",
+  "version": "0.17.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": [