kopular 1.1.1 → 1.1.3

package/GUIDE.md

@@ -27,8 +27,12 @@ both scripts). `ks check src/app.ks` type-checks without building, if you just w
 - No implicit `this` — every member reference is `this.Field`/`this.Method()`, always,
   including inside a lambda.
 - `if`/`else`/`while`/`for`/`foreach (Type x in xs)` — all statements, no ternary. Use
-  `match` for a conditional value: `match x { 1 => "one", _ => "other" }` (the `_` arm is
-  required unless every case is covered, e.g. an enum).
+  `match` for a conditional value: `match x { "a" => "one", _ => "other" }`. **The subject
+  must be `string` or an `enum` — never `bool`/`number`/anything else, and every pattern
+  must be a string literal (or, for an enum subject, an `Enum.Member` name) — not a number,
+  not `true`/`false`.** The `_` arm is required unless every case is covered (only possible
+  for an enum subject, by naming every member). For a `bool`, use `if`/`else` instead —
+  there's no equivalent shorthand.
 - Lambdas need explicit parameter types: `(number x) => x * 2`.
 - Nullable: `string? name` — a nullable field forces `if (x != null) { ... }` before use;
   narrowing is scoped to that `if` block, not reachability-based (an early
@@ -43,6 +47,18 @@ both scripts). `ks check src/app.ks` type-checks without building, if you just w
   `.Slice(a, b)/.Concat(ys)/.Join(sep)/.Reduce(fn, initial)`.
 - `x == null` / `x != null` also match `undefined` — a missed `Array.Find`, an absent
   optional field, etc. all read as `null`.
+- **No `.Match()`/`.Test()`/`.Exec()` on `string` — there is no direct regex-execute method
+  at all.** A regex literal (`r"^[a-z]+$"`) only means something as a `match` *pattern*.
+  The idiomatic way to classify or extract by character class is `.Split("")` (splits into
+  a `string[]` of single characters) plus `match` per character:
+  ```ks
+  bool isLetter = match c { r"^[a-z]$" => true, _ => false };
+  ```
+  Build up runs (words, tokens, ...) by iterating those characters and appending to an
+  accumulator string, flushing it whenever a non-matching character (or the end) is
+  reached — this covers tokenizing/extracting by character class without ever needing a
+  hand-written JS shim. Reach for a real shim (below) only for something a `match` pattern
+  genuinely can't express, like capturing a submatch.
 - No object-literal syntax anywhere (`{ key: value }` doesn't exist as a value). A JS API
   that needs one (rare — `fetch`'s options, `addEventListener`'s options object) needs a
   small hand-written `.js` shim; Kopular's own `Http`/`FormField` cover the common cases so
@@ -68,10 +84,31 @@ need one: `this.SomeService.Count.Subscribe((v) => this.Update());` in the const
 
 **Template bindings**: `{{ expr }}` text, `[prop]="expr"` (real fields for
 `id`/`className`/`value`/`disabled`/`checked`; anything else is a plain attribute),
-`(click)`/`(input)`/`(blur)`/`(change)` events, `[(value)]="Field"` two-way binding
-(`Field` can be a bare name, `this.Field`, or a path like `Qty.Value` — not a method call),
-`*if="expr"`, `*for="Type v of expr"` (element type required, no inference), `*mount="expr"`
-(embeds a live child component, composes with `*for`).
+`(click)`/`(input)`/`(blur)`/`(change)` events, `*if="expr"`, `*for="Type v of expr"`
+(element type required, no inference), `*mount="expr"` (embeds a live child component,
+composes with `*for`).
+
+**Two-way binding, `[(value)]="Field"`** — `Field` can be a bare name, `this.Field`, or a
+member path; it's assigned back directly (`Field = e.target.value`), so it must resolve
+to something assignable, never a method call. **A `state<T>` field needs `.Value` on the
+end** — `[(value)]="Qty.Value"`, not `[(value)]="Qty"` (a bare `state<T>` isn't itself a
+`string`, so binding it directly is a type error):
+```ks
+public state<string> Qty;
+constructor() : base() { this.Qty = state("1"); }
+```
+```html
+<input [(value)]="Qty.Value" />
+```
+
+**Exactly one top-level element per template — no auto-wrapping, a hard compile error
+otherwise.** Wrap multiple top-level pieces in one real container element:
+```html
+<div>
+  <input id="text" [(value)]="Draft" />
+  <button (click)="Submit()">Go</button>
+</div>
+```
 
 **Hand-written `Render()`** (needed when logic is too dynamic for a template, or a template
 would obscure more than it clarifies):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "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",