kopular 1.4.0 → 1.4.3

package/GUIDE.md

@@ -49,65 +49,46 @@ building, for when you only want the errors.
 ## The language you need
 
 - `Type name = value;` for every local — no `let`/`var`, no inference on declarations.
-- 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 { "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.
+- No implicit `this`: every member is `this.Field`/`this.Method()`, inside lambdas too.
+- `if`/`else`/`while`/`for`/`foreach (Type x in xs)`; no ternary. For a conditional value use
+  `match x { "a" => "one", _ => "other" }` — **the subject must be a `string` or an `enum`,
+  every pattern a string literal (or `Enum.Member`), never a number or `true`/`false`.** `_`
+  is required unless an enum's members are all named. For a `bool`, use `if`/`else`.
 - Lambdas need explicit parameter types: `(number x) => x * 2`.
-- Operators: `+ - * / %`, `== != < > <= >=`, `&& || !` — `!` is a real unary operator on a
-  `bool` (`if (!done)`, `bool flipped = !done;`). Precedence, low → high: `=` → `||` →
-  `&&` → `==` `!=` → `<` `>` `<=` `>=` → `+` `-` → `*` `/` `%` → unary `-` `!` →
-  `.member`/`(call)`/`[index]`. **No `++`/`--`/`+=`** — write `i = i + 1;`.
-- **number → string**: `+` with a string on either side (`"count: " + n`), or interpolation
-  (`$"{n} items left"`). There is no `.ToString()` — calling it is `KS4085`.
-- `try { } catch (string e) { } finally { }` and `throw "message";` all exist — one `catch`
-  per `try`, and its parameter type is your choice (it is *not* checked against what was
-  actually thrown).
-- **Comments are `//` only** — there is no `/* ... */` block comment, and a `/*` is a parse
-  error (`KS2020`), not an ignored region.
-- **Reserved words**: naming a local or parameter one of these is a parse error, not
-  shadowing — `raw`, `state`, `task`, `from`, `as`, `get`, `set`, `in`, `base` and `match`
-  are the ones easy to pick by accident. Full list: `using extern raw template styles from
-  as const class interface enum constructor public private protected static virtual override
-  get set return if else while for foreach in break continue match this base new void true
-  false null task state async await try catch finally throw`.
-- Nullable: `string? name` — a nullable field forces `if (x != null) { ... }` before use;
-  narrowing is scoped to that `if` block, not reachability-based (an early
-  `if (x == null) { return; }` does NOT narrow `x` afterward — wrap the rest in
-  `if (x != null) { ... }` instead).
+- Operators: `+ - * / %`, `== != < > <= >=`, `&& || !` (`!` works on a `bool`: `if (!done)`).
+  Precedence low → high: `=`, `||`, `&&`, `== !=`, `< > <= >=`, `+ -`, `* / %`, unary `- !`,
+  then `.member`/`(call)`/`[index]`. **No `++`/`--`/`+=`** — write `i = i + 1;`.
+- **number → string**: `"count: " + n` or `$"{n} items left"`. There is no `.ToString()`
+  (`KS4085`).
+- `try { } catch (string e) { } finally { }` and `throw "message";` — one `catch` per `try`;
+  its parameter type isn't checked against what was thrown.
+- **Comments are `//` only** — `/*` is a parse error (`KS2020`).
+- **Reserved words** — easy to pick by accident as a local or parameter name, and a parse
+  error if you do: `raw`, `state`, `task`, `from`, `as`, `get`, `set`, `in`, `base`, `match`,
+  `template`, `styles`, `const`, `async`, `await`, plus the usual keywords.
+- Nullable: `string? name` must be checked with `if (x != null) { ... }` before use, and
+  narrowing only lasts inside that block — an early `if (x == null) { return; }` does NOT
+  narrow `x` afterward.
 - Strings: `s.Length`, `.Contains()/.StartsWith()/.EndsWith()`, `.Trim()/.ToUpper()/.ToLower()`,
   `.Split(sep)`, `.Replace(from, to)`, `.CompareTo(other)` (sort comparator), `+` concatenates.
-  Both `"double"` and `'single'` quotes work — use whichever the other isn't, e.g. inside
-  a template attribute (`*if="Name != ''"`).
-- Arrays are created with a literal and nothing else: `number[] xs = [];`, `[1, 2, 3]`,
-  `[new Todo("a")]`. **There is no `new number[3]` form** — that's a parse error, not an
-  empty array.
-- Arrays: `xs.Length`, `.Map()/.Filter()/.ForEach()/.Find()/.FindIndex()/.Includes()/.IndexOf()`,
-  `.Sort(cmp)/.Reverse()/.Push(x)` (all three **non-mutating**, return a new array),
+  `"double"` and `'single'` quotes both work — handy inside a template attribute
+  (`*if="Name != ''"`).
+- Arrays come only from literals: `number[] xs = [];`, `[1, 2, 3]`, `[new Todo("a")]` —
+  **`new number[3]` is a parse error.** Methods: `xs.Length`,
+  `.Map()/.Filter()/.ForEach()/.Find()/.FindIndex()/.Includes()/.IndexOf()`,
+  `.Sort(cmp)/.Reverse()/.Push(x)` (all three **non-mutating** — they return a new array),
   `.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:
+- `x == null` also matches `undefined` (a missed `Find`, an absent field).
+- **No regex methods on `string`** (`.Match()`/`.Test()`/`.Exec()` don't exist). A regex
+  literal works only as a `match` pattern, so to classify or tokenize by character class,
+  `.Split("")` into characters and `match` each one, appending to an accumulator and flushing
+  it at each non-matching character and at the end:
   ```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
-  you'll rarely hit this.
+  Only something a pattern can't express (capturing a submatch) needs a `.js` shim.
+- No object literals (`{ key: value }` isn't a value). The rare JS API that needs one
+  needs a small `.js` shim; `Http`/`FormField` cover the common cases.
 
 ## Components
 
@@ -123,7 +104,8 @@ handlers don't count. State on *another* object does still need one:
 **Template bindings**: `{{ expr }}` text, `[prop]="expr"` (real fields for
 `id`/`className`/`value`/`disabled`/`checked`; anything else is a plain attribute),
 `(click)`/`(input)`/`(blur)`/`(change)`/`(submit)` events (`(submit)` calls `preventDefault()`
-for you, and Enter in a form's input fires it), text mixed with elements
+for you, and Enter in a form's input fires it; validating in code? put `novalidate` on the
+`<form>`, or the browser's own `type="email"`/`required` checks block the submit first), text mixed with elements
 (`<label>Email <input></label>`), `*if="expr"`, `*for="Type v of expr"`
 (element type required, no inference), `*mount="expr"` (embeds a live child component,
 composes with `*for`).
@@ -150,44 +132,8 @@ otherwise.** Wrap multiple top-level pieces in one real container element:
 </div>
 ```
 
-**Hand-written `Render()`** (needed when logic is too dynamic for a template, or a template
-would obscure more than it clarifies):
-
-```ks
-public override VElement Render() {
-  VElement button = VElement.Create("button");
-  button.TextContent = "Count: " + this.Count.Value;
-  button.OnClick = (Event e) => { this.Increment(); };
-  return button;
-}
-```
-`VElement.Create(tag)`, `.TextContent/.ClassName/.Id/.Value/.RawHtml/.Disabled/.Checked`,
-`.OnClick/.OnInput/.OnBlur/.OnChange`, `.AppendChild(child)`, `.SetAttr(name, value)` (the
-escape hatch for anything without a named field). Both styles compile to the same thing and
-mix freely across a project.
-
-**Conditional value**: there's no ternary, so to pick between two elements use `If()` (from
-`kopular/directives`, already covered by `using "kopular"`):
-```ks
-root.AppendChild(If(this.On.Value, () => this.Yes(), () => this.No()));
-```
-
-**Error boundary**: override `RenderError(string message)` to show a fallback instead of an
-uncaught crash if `Render()` throws.
-
-## Nested components & content projection
-
-```ks
-this.Items.ForEach((Item item) => {
-  VElement slot = VElement.Mount(item);  // item : Component, e.g. its own `public string Id;`
-  slot.Id = item.Id;                     // stable key for reordering
-  list.AppendChild(slot);
-});
-```
-A template does the same via `<li *for="Item i of Items" *mount="i"></li>`.
-
-Content projection (React's `children`): pass a `() => VElement` into a constructor, call
-it from `Render()` — no separate mechanism needed.
+**Beyond templates** — a hand-written `Render()` (the `VElement` API), `If()`, and the
+`RenderError` error boundary are in `LLM.md`; templates cover typical app work.
 
 ## Services — no DI container
 
@@ -232,7 +178,7 @@ nav.Mount(document.body);
   `redirectPath` (via `pushState`, so the URL changes too). `guard` itself decides which
   paths it cares about, and `redirectPath` is never guard-checked, so pick one the guard
   always allows. Defaults to always-allow.
-- `AddLazyRoute(path, loader)` for real code-splitting — see "Lazy routes" below.
+- `AddLazyRoute(path, loader)` for real code-splitting — see `LLM.md`.
 - Every deploy target needs its own SPA fallback (serve `index.html` for any route with no
   matching file) — a plain HTTP limitation, not a Kopular one.
 
@@ -311,46 +257,11 @@ match r.Status.Value {
 };
 ```
 
-## Scoped styles
-
-```ks
-class Widget : Component {
-  constructor() : base() { }   // required: 'styles from' has to have one to initialize from
-  template from "./widget.html";
-  styles from "./widget.css";
-}
-```
-Every selector in `widget.css` is rewritten to only match this class's own elements —
-never a sibling's or child's. Needs a constructor to exist on the class.
-
-## Lazy routes (real code-splitting)
+## More in `node_modules/kopular/LLM.md`
 
-```js
-// admin_page_loader.js — hand-written, not compiled from .ks
-export async function LoadAdminPage() {
-  const { AdminPage } = await import("./admin_page.js");
-  return new AdminPage();
-}
-```
-```ks
-extern task<Component> LoadAdminPage() from "./admin_page_loader";
-nav.AddLazyRoute("/admin", LoadAdminPage);
-```
-The lazy page (`admin_page.ks`) must be built as its own entry too — it's deliberately not
-`using`'d from your app's entry (that's what keeps it out of the eager bundle), so add a
-second build line: `ks build src/app.ks && ks build src/admin_page.ks`. Testing it via
-`kopular/testing`'s `runKopularApp` needs no extra setup — it compiles any file in your
-`srcDir` the entry doesn't reach.
-
-## Testing
-
-```js
-import { runKopularApp } from "kopular/testing";
-const { window, cleanup } = await runKopularApp(srcDir, "app.ks", { includeKopularPackage: true });
-// assert against window.document, then:
-cleanup();
-```
-Real jsdom, real compile, real DOM assertions — not a mock.
+Nested components (`*mount`, `VElement.Mount`) and content projection, scoped styles
+(`styles from`), lazy routes (`AddLazyRoute`), and testing (`kopular/testing`'s
+`runKopularApp`).
 
 ## Common mistakes
 

package/LLM.md

@@ -125,8 +125,12 @@ extern class VElement {
   (Event) => void OnInput { get; set; }
   (Event) => void OnBlur { get; set; }
   (Event) => void OnChange { get; set; }
+  // Calls preventDefault() before the handler — a form submit never reloads the page.
+  (Event) => void OnSubmit { get; set; }
   void AppendChild(VElement child);
   void SetAttr(string name, string value);
+  // A bare text node, for text next to elements in one parent.
+  static VElement Text(string content);
   // Embeds a live child Component as this slot's content — see "Nested
   // component composition" below. Declared taking a concrete Component
   // rather than Kopular's own Mountable interface: extern declarations
@@ -299,8 +303,8 @@ w.Bump();                // re-render + diff + patch
   `innerHTML`, unescaped: only ever assign static/developer-authored content — a `raw
   string ... from "<path>.html";` compile-time constant, in every real use in this
   ecosystem today — never anything reachable from user input, a fetched `Http` response
-  body, or a `FormField<T>`'s `.Value`, or it's a real XSS hole**), the four fixed named
-  event fields `OnClick`/`OnInput`/`OnBlur`/`OnChange` (each a real no-op by default, never
+  body, or a `FormField<T>`'s `.Value`, or it's a real XSS hole**), the five fixed named
+  event fields `OnClick`/`OnInput`/`OnBlur`/`OnChange`/`OnSubmit` (each a real no-op by default, never
   null — no nullable function type to fall back on), `AppendChild(child)`, and
   `SetAttr(name, value)` (the escape hatch for any other real HTML attribute — `href`,
   `src`, `alt`, `placeholder`, ...; never `Value`, see above). `Id` doubles as a stable key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "1.4.0",
+  "version": "1.4.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",
@@ -66,7 +66,7 @@
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",
-    "kopscript": "^1.3.0",
+    "kopscript": "^1.4.0",
     "typescript": "^5.5.0",
     "vitest": "^4.1.11"
   },