kopscript 0.17.0 → 0.18.0

package/LLM.md

@@ -550,6 +550,12 @@ class Counter : Component {
   `[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.
@@ -558,7 +564,7 @@ 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*
   (`VElement.Create`/`.AppendChild`/`.TextContent`/`.SetAttr`/the named `On*` event fields)

package/README.md

@@ -606,10 +606,22 @@ Supported bindings and directives:
 | `{{ 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
@@ -620,8 +632,8 @@ 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* —

package/dist/template_compiler.js

@@ -234,6 +234,8 @@ export class TemplateCompiler {
             };
             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) {
@@ -301,4 +303,34 @@ export class TemplateCompiler {
         }
         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,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.17.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",