kopular 0.13.0 → 0.14.1

package/src/velement.ks

@@ -0,0 +1,95 @@
+using "./dom";
+
+// A lightweight, framework-owned description of one DOM element — Render()
+// builds a tree of these instead of real DOM nodes, so Update() can DIFF
+// the new tree against the previous one and patch only what changed,
+// instead of discarding and rebuilding the whole real DOM subtree every
+// time (see src/vdom.ks for the diff/patch engine, src/component.ks for
+// where Render()'s return type changed from Element to VElement).
+//
+// Fixed, named fields — not a generic prop bag — because KopScript has no
+// object-literal syntax to build one with. Fixed, named event slots — not
+// an array of handlers — because KopScript has no array-of-function-values
+// type either. Both are real language constraints, not an oversight; see
+// SetAttr below for the escape hatch covering everything not common enough
+// to deserve its own named field.
+class VElement {
+  public string Tag;
+  // Mutually exclusive with Children and RawHtml — set at most one of the
+  // three. TextContent/Children mirrors the same "no mixed text/element
+  // content" rule KopScript's own templates already enforce.
+  public string TextContent;
+  public string ClassName;
+  public string Id;
+  // The one property patched via direct assignment, never setAttribute —
+  // see Element.value's own comment in dom.ks for why (the "default value
+  // attribute" vs "current live value property" DOM footgun — the exact
+  // property behind the original typing bug this whole effort traces to).
+  public string Value;
+  public VElement[] Children;
+  // An opaque, undiffed leaf — set instead of TextContent/Children for the
+  // existing raw-HTML-then-wire-handlers pattern (header.ks/nav.ks). The
+  // patch engine treats two VElements with different RawHtml as a single
+  // innerHTML assignment, never recursing inside it — the same "opaque
+  // blob" treatment `raw string` already gets everywhere else.
+  public string RawHtml;
+
+  // Each defaults to a real no-op, never null — KopScript has no nullable
+  // *function* type to fall back on for "no handler set" (see Router.Guard
+  // for the same default-real-function pattern already established).
+  public (Event) => void OnClick;
+  public (Event) => void OnInput;
+  public (Event) => void OnBlur;
+  public (Event) => void OnChange;
+
+  // A real HTML attribute not common enough for its own named field (href,
+  // src, alt, placeholder, ...) — parallel arrays, since KopScript has no
+  // Dictionary type. Never Value (see its own field comment above). Public,
+  // read directly by the patch engine (src/vdom.ks) rather than through
+  // accessor methods — plain data, same style as this codebase's other
+  // plain classes (Note, Dog, ...).
+  public string[] ExtraNames;
+  public string[] ExtraValues;
+
+  // Set only once this VElement has been materialized into (or reused as)
+  // a real DOM node — null on a freshly-built tree from a not-yet-patched
+  // Render() call. The patch engine reads the *previous* render's tree's
+  // RealNode to know what to reuse/patch; it never reads the live DOM back
+  // to rediscover this (see vdom.ks's own header comment for why).
+  public Element? RealNode;
+
+  constructor(string tag) {
+    this.Tag = tag;
+    this.TextContent = "";
+    this.ClassName = "";
+    this.Id = "";
+    this.Value = "";
+    this.Children = [];
+    this.RawHtml = "";
+    this.OnClick = (Event e) => {};
+    this.OnInput = (Event e) => {};
+    this.OnBlur = (Event e) => {};
+    this.OnChange = (Event e) => {};
+    this.ExtraNames = [];
+    this.ExtraValues = [];
+    this.RealNode = null;
+  }
+
+  public static VElement Create(string tag) {
+    return new VElement(tag);
+  }
+
+  public void AppendChild(VElement child) {
+    this.Children = this.Children.Push(child);
+  }
+
+  // Last call for a given name wins if SetAttr is called more than once
+  // with the same name on one VElement — the patch engine applies
+  // ExtraNames/ExtraValues in order, so a later entry's setAttribute call
+  // simply overwrites an earlier one for the same name, no special
+  // dedup/replace logic needed here.
+  public void SetAttr(string name, string value) {
+    this.ExtraNames = this.ExtraNames.Push(name);
+    this.ExtraValues = this.ExtraValues.Push(value);
+  }
+}