kopular 0.17.1 → 0.18.0

package/LLM.md

@@ -98,6 +98,12 @@ extern class VElement {
   (Event) => void OnChange { get; set; }
   void AppendChild(VElement child);
   void SetAttr(string name, string value);
+  // 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
+  // don't model inheritance/interface conformance between separate extern
+  // classes, and every real caller passes a Component subclass anyway.
+  static VElement Mount(Component component);
 } from "kopular/velement";
 
 extern class Component {
@@ -106,6 +112,9 @@ extern class Component {
   virtual void AfterRender(Element root); // see "Component" below
   void Mount(Element parent);
   void Update();
+  // Called once when this component is removed from its parent's tree via
+  // VElement.Mount above — see "Nested component composition" below.
+  virtual void OnUnmount();
 } from "kopular/component";
 
 extern class Router {
@@ -275,6 +284,23 @@ w.Bump();                // re-render + diff + patch
     components, a modal that comes and goes.
   - Hand-written `Render()` only — there's no template (`.html`) syntax yet for embedding a
     child component the way `*if`/`*for` embed structural logic.
+- **Content projection (React's `children`/Angular's `<ng-content>`) needs no separate
+  mechanism** — pass a `() => VElement` into a child's constructor and call it from inside
+  its own `Render()`; it's invoked fresh every render and closes over the parent's `this`,
+  so projected content reflects the parent's current state on every patch:
+  ```ks
+  class Card : Component {
+    private () => VElement ContentBuilder;
+    constructor(() => VElement contentBuilder) : base() { this.ContentBuilder = contentBuilder; }
+    public override VElement Render() {
+      VElement div = VElement.Create("div");
+      div.AppendChild(this.ContentBuilder());
+      return div;
+    }
+  }
+  ```
+  More than one slot: one named `() => VElement` callback per slot (same fixed-named-slot
+  convention as `VElement`'s own `OnClick`/etc.), not a generic bag.
 - **`Update()` before `Mount()` is a safe no-op**, not an error. This matters for two
   sibling `Component`s (e.g. two `Router` pages) that share one injected service's
   `state<T>` and both `Subscribe()` it — every route's page is constructed eagerly (see

package/README.md

@@ -468,6 +468,65 @@ removal to get right, so there's nothing this mechanism would add there. Reach f
 `VElement.Mount` for anything with real add/remove/reorder: a list of components, a modal
 that comes and goes, anything genuinely dynamic.
 
+## Content projection — a parent giving a child what to render
+
+React's `children` prop and Angular's `<ng-content>` both let a parent hand a child
+arbitrary markup to render at a spot the child itself decides. Kopular needs no separate
+mechanism for this at all: pass a `() => VElement` into the child's constructor, the same
+as any other constructor argument, and have the child call it from inside its own
+`Render()`:
+
+```ks
+class Card : Component {
+  private () => VElement ContentBuilder;
+  constructor(() => VElement contentBuilder) : base() {
+    this.ContentBuilder = contentBuilder;
+  }
+  public override VElement Render() {
+    VElement div = VElement.Create("div");
+    div.ClassName = "card";
+    div.AppendChild(this.ContentBuilder());
+    return div;
+  }
+}
+
+// Usage — the parent decides what's inside the card, Card decides the chrome around it:
+Card card = new Card(() => this.BuildCardBody());
+```
+
+Because the callback is invoked fresh on every one of `Card`'s own renders (not a value
+captured once and frozen), and it's a closure over the *parent's* own `this`, the projected
+content reflects the parent's current state every time — bump a field the parent's own
+`BuildCardBody()` reads, call the parent's `Update()`, and `Card`'s own next patch shows the
+new value, patched in place like any other content. No new API: this is just
+`VElement.Mount` plus an ordinary function-typed constructor argument, the same "no hidden
+magic, explicit constructor args" pattern dependency injection above already uses.
+
+More than one projection point works the same way — one named callback per slot, the same
+fixed-named-slot convention `VElement`'s own `OnClick`/`OnInput`/`OnBlur`/`OnChange` already
+use rather than a generic, unordered bag:
+
+```ks
+class Panel : Component {
+  private () => VElement HeaderBuilder;
+  private () => VElement BodyBuilder;
+  constructor(() => VElement headerBuilder, () => VElement bodyBuilder) : base() {
+    this.HeaderBuilder = headerBuilder;
+    this.BodyBuilder = bodyBuilder;
+  }
+  public override VElement Render() {
+    VElement div = VElement.Create("div");
+    VElement header = VElement.Create("header");
+    header.AppendChild(this.HeaderBuilder());
+    div.AppendChild(header);
+    VElement body = VElement.Create("section");
+    body.AppendChild(this.BodyBuilder());
+    div.AppendChild(body);
+    return div;
+  }
+}
+```
+
 ## HTTP
 
 ```ks

package/package.json

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