kopular 0.13.0 → 0.15.0

package/src/vdom.ks

@@ -0,0 +1,277 @@
+using "./dom";
+using "./velement";
+
+// The diff/patch engine behind real vdom diffing: Component.Update() (see
+// component.ks) calls Patch() with the PREVIOUS render's VElement tree
+// (which carries each node's real, live DOM counterpart via its own
+// RealNode field) and the NEW tree Render() just produced, and gets back
+// real DOM mutated/reused in place wherever possible instead of a full
+// subtree rebuild.
+//
+// Deliberately never reads the live DOM back to rediscover structure (no
+// "get current children"/"get current tag" API exists, or is needed) —
+// the retained *previous* VElement tree already records everything Patch()
+// needs to know about what's currently there. This is what makes the whole
+// approach work without a generic children/attributes read-back API that
+// KopScript's narrow, curated DOM binding doesn't have.
+
+// Builds a brand-new, fully real DOM subtree from a VElement tree with no
+// diffing at all — first mount, or whenever Patch() decides a subtree must
+// be replaced outright (no previous node to reuse, or the tag changed).
+// Mutates `tree.RealNode` (and recursively every descendant's) as a side
+// effect, so the tree this was called on becomes the new "previous tree"
+// the next Patch() call diffs against.
+Element Materialize(VElement tree) {
+  Element el = document.createElement(tree.Tag);
+
+  if (tree.RawHtml.Length > 0) {
+    el.innerHTML = tree.RawHtml;
+  } else if (tree.Children.Length > 0) {
+    foreach (VElement child in tree.Children) {
+      el.appendChild(Materialize(child));
+    }
+  } else {
+    el.textContent = tree.TextContent;
+  }
+
+  el.className = tree.ClassName;
+  el.id = tree.Id;
+  el.value = tree.Value;
+
+  for (number i = 0; i < tree.ExtraNames.Length; i = i + 1) {
+    el.setAttribute(tree.ExtraNames[i], tree.ExtraValues[i]);
+  }
+
+  // Skip attaching VElement's own shared no-op (see velement.ks) — it does
+  // nothing when invoked, so registering it costs real work (a listener
+  // list entry, held onto for nothing) for zero benefit. A real handler
+  // (never equal to the shared no-op) always gets attached as before.
+  if (tree.OnClick != NoOpEventHandler) { el.addEventListener("click", tree.OnClick); }
+  if (tree.OnInput != NoOpEventHandler) { el.addEventListener("input", tree.OnInput); }
+  if (tree.OnBlur != NoOpEventHandler) { el.addEventListener("blur", tree.OnBlur); }
+  if (tree.OnChange != NoOpEventHandler) { el.addEventListener("change", tree.OnChange); }
+
+  tree.RealNode = el;
+  return el;
+}
+
+// Diffs `updated` against `old` (the previous render's tree for this exact
+// position, or null if there is none — first mount) and returns the real
+// DOM node now representing `updated`, reusing `old`'s real node in place
+// whenever the tag matches. `parent` is only used to attach/replace at the
+// top of whatever subtree Patch() is called on — child-level attach/replace
+// happens inside PatchChildren.
+//
+// Deliberately all positive-branch `if (x != null) { ... } else { ... }`,
+// never an early-return guard clause — KopScript's nullable narrowing is
+// scope-based, not reachability-based, so `if (x == null) { return; }
+// use(x);` would NOT narrow `x` afterward (see KopScript's own LLM.md "Common
+// mistakes"). Every nullable member-access path (`oldTree.RealNode`,
+// never narrows directly either) is read into a local first for the same
+// reason.
+Element Patch(Element parent, VElement? old, VElement updated) {
+  if (old != null) {
+    VElement oldTree = old;
+    Element? maybeOldNode = oldTree.RealNode;
+    if (maybeOldNode != null) {
+      Element realNode = maybeOldNode;
+      if (oldTree.Tag != updated.Tag) {
+        Element created = Materialize(updated);
+        parent.replaceChild(created, realNode);
+        return created;
+      } else {
+        updated.RealNode = realNode;
+
+        if (updated.RawHtml.Length > 0 || oldTree.RawHtml.Length > 0) {
+          if (updated.RawHtml != oldTree.RawHtml) {
+            realNode.innerHTML = updated.RawHtml;
+          }
+        } else {
+          if (updated.TextContent != oldTree.TextContent) {
+            realNode.textContent = updated.TextContent;
+          }
+          PatchChildren(realNode, oldTree.Children, updated.Children);
+        }
+
+        if (updated.ClassName != oldTree.ClassName) {
+          realNode.className = updated.ClassName;
+        }
+        if (updated.Id != oldTree.Id) {
+          realNode.id = updated.Id;
+        }
+        // Always assigned, never conditionally on updated.Value != oldTree.Value
+        // — unlike TextContent/ClassName/Id, an <input>/<select>'s live value
+        // can diverge from the last-recorded VElement.Value purely through
+        // user interaction (typing, picking an option) with no Update() ever
+        // running in between (a real, deliberate pattern — see KopularDemo's
+        // dogs_page.ks, which never Update()s on input/change). The recorded
+        // oldTree.Value only reflects the tree as of the last actual render,
+        // so comparing against it can't tell "genuinely unchanged" apart from
+        // "changed live in the DOM since then, framework never told" — the
+        // same reason a real "controlled input" (React's own term for this)
+        // always writes value on every render rather than diffing it.
+        realNode.value = updated.Value;
+
+        // Same-length is the overwhelmingly common case (the same Render()
+        // code path calls SetAttr the same number of times, in the same
+        // order, on every call) — compare aligned by index and only touch
+        // the real DOM for an entry that actually changed, rather than
+        // reapplying every extra attribute on every patch regardless. A
+        // length mismatch (the rarer case: a SetAttr call was added,
+        // removed, or made conditional between renders) falls back to
+        // reapplying everything, since index-aligned comparison isn't
+        // meaningful once the two arrays don't correspond entry-for-entry.
+        if (updated.ExtraNames.Length == oldTree.ExtraNames.Length) {
+          for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {
+            if (updated.ExtraNames[i] != oldTree.ExtraNames[i] || updated.ExtraValues[i] != oldTree.ExtraValues[i]) {
+              realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+            }
+          }
+        } else {
+          for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {
+            realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+          }
+        }
+
+        // Swap a listener only when the handler reference actually changed.
+        // A node that never sets a real OnClick/OnInput/OnBlur/OnChange
+        // keeps VElement's own shared NoOpEventHandler reference on both
+        // sides (see velement.ks) — comparing by `!=` costs nothing and
+        // skips two real DOM API calls per event per node for the (common)
+        // case of "this node has no handler of this kind either time,"
+        // which matters a lot on a list with hundreds/thousands of rows
+        // most of which set at most one or two of the four. A node WITH a
+        // real handler still gets a fresh closure every render (it
+        // captures per-render values, like a loop's own item), so it still
+        // swaps every time — correctly, since the old closure really is
+        // stale.
+        if (updated.OnClick != oldTree.OnClick) {
+          realNode.removeEventListener("click", oldTree.OnClick);
+          realNode.addEventListener("click", updated.OnClick);
+        }
+        if (updated.OnInput != oldTree.OnInput) {
+          realNode.removeEventListener("input", oldTree.OnInput);
+          realNode.addEventListener("input", updated.OnInput);
+        }
+        if (updated.OnBlur != oldTree.OnBlur) {
+          realNode.removeEventListener("blur", oldTree.OnBlur);
+          realNode.addEventListener("blur", updated.OnBlur);
+        }
+        if (updated.OnChange != oldTree.OnChange) {
+          realNode.removeEventListener("change", oldTree.OnChange);
+          realNode.addEventListener("change", updated.OnChange);
+        }
+
+        return realNode;
+      }
+    } else {
+      // Shouldn't happen in practice (every previously-rendered tree has a
+      // real node by the time a second render diffs against it) — treated
+      // as "nothing to reuse" rather than a crash, same defensive spirit
+      // as Component's own IsMounted guard.
+      Element created = Materialize(updated);
+      parent.appendChild(created);
+      return created;
+    }
+  } else {
+    Element created = Materialize(updated);
+    parent.appendChild(created);
+    return created;
+  }
+}
+
+// Keyed reconciliation: each VElement's own Id is its key when non-empty —
+// a real, existing DOM convention, needing no new API or syntax. A new
+// child whose Id matches an old child's Id is patched against that old
+// child (reusing its real node) regardless of position; a new child with
+// no Id, or an Id not present among the old children, falls back to
+// pairing positionally against whatever old children are still unconsumed,
+// in order. DOCUMENTED, REAL LIMITATION: without stable Ids, a reordered
+// list still produces the correct final output, but a given item's real
+// DOM node (and anything stateful attached to it, like focus) isn't
+// guaranteed to follow its data across the reorder — give list items a
+// stable Id for that guarantee.
+void PatchChildren(Element parent, VElement[] oldChildren, VElement[] newChildren) {
+  // Map, not a Push loop — Push is deliberately non-mutating (a real
+  // spread-copy every call, see KopScript's own README), so building an
+  // n-length array by Push-ing once per element in a loop is an
+  // accidental O(n^2) on every single PatchChildren call, however small
+  // the actual diff. Map is a real, single O(n) pass straight to
+  // Array.prototype.map.
+  bool[] oldConsumed = oldChildren.Map((VElement c) => false);
+  number[] matchedOldIndex = newChildren.Map((VElement c) => -1);
+
+  // Pass 1: keyed matches, by Id.
+  for (number i = 0; i < newChildren.Length; i = i + 1) {
+    if (newChildren[i].Id.Length == 0) { continue; }
+    for (number j = 0; j < oldChildren.Length; j = j + 1) {
+      if (!oldConsumed[j] && oldChildren[j].Id == newChildren[i].Id) {
+        matchedOldIndex[i] = j;
+        oldConsumed[j] = true;
+        break;
+      }
+    }
+  }
+
+  // Pass 2: positional fallback for everything Pass 1 didn't match —
+  // pair each remaining new child against the next still-unconsumed old
+  // child, in order.
+  number nextOld = 0;
+  for (number i = 0; i < newChildren.Length; i = i + 1) {
+    if (matchedOldIndex[i] >= 0) { continue; }
+    while (nextOld < oldChildren.Length && oldConsumed[nextOld]) {
+      nextOld = nextOld + 1;
+    }
+    if (nextOld < oldChildren.Length) {
+      matchedOldIndex[i] = nextOld;
+      oldConsumed[nextOld] = true;
+      nextOld = nextOld + 1;
+    }
+  }
+
+  // Whether anything is actually moving at all — same length, and every
+  // new position matched the *same* old position. The extremely common
+  // case for a list that's only had some of its rows' own content change
+  // (e.g. "update every 10th row"), where reconciliation still has real
+  // work to do (see Pass 1/2 above and Patch() itself) but nothing needs
+  // to physically move in the DOM at all.
+  bool needsReorder = oldChildren.Length != newChildren.Length;
+  for (number i = 0; i < newChildren.Length; i = i + 1) {
+    if (matchedOldIndex[i] != i) {
+      needsReorder = true;
+      break;
+    }
+  }
+
+  // Pass 3: patch/create each new child in order, then — only if the list
+  // actually needs reordering — move it into its correct final position.
+  // appendChild on a node already attached elsewhere in the DOM MOVES it
+  // (real DOM semantics), so processing new children in their final
+  // desired order and always appending naturally builds up the correct
+  // sequence, no separate insertBefore/reference-node bookkeeping needed.
+  // Safe because VElement.Children is always the COMPLETE list of a
+  // node's children — nothing else ever shares `parent`. Skipping the
+  // move entirely when `needsReorder` is false avoids a real DOM API call
+  // per child for the common no-reorder case — Patch() itself already
+  // updates or replaces a reused/changed node exactly in place either way.
+  for (number i = 0; i < newChildren.Length; i = i + 1) {
+    VElement? matchedOld = null;
+    if (matchedOldIndex[i] >= 0) {
+      matchedOld = oldChildren[matchedOldIndex[i]];
+    }
+    Element childNode = Patch(parent, matchedOld, newChildren[i]);
+    if (needsReorder) {
+      parent.appendChild(childNode);
+    }
+  }
+
+  // Pass 4: remove whatever old children never got reused.
+  for (number j = 0; j < oldChildren.Length; j = j + 1) {
+    if (oldConsumed[j]) { continue; }
+    Element? maybeOldNode = oldChildren[j].RealNode;
+    if (maybeOldNode != null) {
+      Element oldNode = maybeOldNode;
+      parent.removeChild(oldNode);
+    }
+  }
+}

package/src/velement.js

@@ -0,0 +1,37 @@
+import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
+
+export function NoOpEventHandler(e) {
+}
+export class VElement {
+  constructor(tag) {
+    this.Tag = tag;
+    this.TextContent = "";
+    this.ClassName = "";
+    this.Id = "";
+    this.Value = "";
+    this.Children = [];
+    this.RawHtml = "";
+    this.OnClick = NoOpEventHandler;
+    this.OnInput = NoOpEventHandler;
+    this.OnBlur = NoOpEventHandler;
+    this.OnChange = NoOpEventHandler;
+    this.ExtraNames = [];
+    this.ExtraValues = [];
+    this.RealNode = null;
+  }
+
+  static Create(tag) {
+    return new VElement(tag);
+  }
+
+  AppendChild(child) {
+    this.Children = [...this.Children, child];
+  }
+
+  SetAttr(name, value) {
+    this.ExtraNames = [...this.ExtraNames, name];
+    this.ExtraValues = [...this.ExtraValues, value];
+  }
+}
+
+//# sourceMappingURL=velement.js.map

package/src/velement.js.map

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

package/src/velement.ks

@@ -0,0 +1,106 @@
+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).
+//
+// A single shared no-op, not a fresh closure per VElement — every instance
+// that never sets a real handler gets this exact same function reference,
+// so Patch() (vdom.ks) can tell "no handler either time" apart from "a
+// handler changed" with a plain `!=` reference check instead of always
+// removing/re-adding all four DOM listeners on every patch regardless of
+// whether anything about them actually changed. A fresh `(Event e) => {}`
+// closure per instance would defeat this — two "empty" handlers would
+// never compare equal, even when nothing meaningful differs.
+void NoOpEventHandler(Event e) {
+}
+
+// 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 = NoOpEventHandler;
+    this.OnInput = NoOpEventHandler;
+    this.OnBlur = NoOpEventHandler;
+    this.OnChange = NoOpEventHandler;
+    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);
+  }
+}