@kudzujs/core 0.3.0 → 0.4.1

package/README.md

@@ -8,7 +8,7 @@ HTML-first TSX framework with synchronous state semantics and no virtual DOM.
 
 Kudzu keeps the familiar function-component, props, children, event-handler, and `useState` shape. Static components compile to HTML. Simple interactions compile to small behavior commands, while normal sync or async JavaScript handlers compile to external ESM.
 
-> Experimental `0.3.x`: the compiler API and supported TSX surface may change.
+> Experimental `0.4.x`: the compiler API and supported TSX surface may change.
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
@@ -100,15 +100,28 @@ The handler above increments by two and patches its bound DOM once. Inspect the
 
 ## Reactive Attributes
 
-`className`, `disabled`, and controlled `value` accept normal state-dependent TSX expressions:
+`className`, `disabled`, controlled `value`, and controlled `checked` accept normal state-dependent TSX expressions. The same `value` binding works for inputs and selects:
 
 ```tsx
 <div className={active ? "active" : "idle"} />
 <button disabled={loading}>Save</button>
 <input value={name} onInput={event => setName(event.currentTarget.value)} />
+<input type="checkbox" checked={subscribed} onChange={event => setSubscribed(event.currentTarget.checked)} />
+<select value={theme} onChange={event => setTheme(event.currentTarget.value)} />
 ```
 
-Kudzu compiles derived expressions to external ESM and patches only the bound DOM attribute or property.
+Regular attributes use the same expressions without an allowlist:
+
+```tsx
+<button
+  aria-expanded={open}
+  data-state={open ? "open" : "closed"}
+  hidden={!visible}
+  title={open ? "Close menu" : "Open menu"}
+/>
+```
+
+Kudzu compiles derived expressions to external ESM and patches only the bound DOM attribute or property. `aria-*` and `data-*` boolean values serialize as `"true"` or `"false"`; ordinary false values remove the attribute. Reactive `style`, `ref`, and `dangerouslySetInnerHTML` remain unsupported.
 
 ## Conditional DOM
 
@@ -131,6 +144,32 @@ Logical state persists across branch switches, while uncontrolled DOM state rese
 
 Reactive conditional DOM currently targets the HTML namespace and is rejected inside SVG or MathML.
 
+## Keyed Lists
+
+Map local array state directly to one keyed JSX element per item:
+
+```tsx
+const [items, setItems] = useState([
+  { id: 1, name: "Oak", done: false },
+  { id: 2, name: "Pine", done: true }
+])
+
+<ul>{items.map(item =>
+  <li
+    key={item.id}
+    className={item.done ? "done" : "active"}
+    aria-label={`${item.name} item`}
+  >
+    {item.name.toUpperCase()}
+    <button onClick={() => setItems(items.filter(entry => entry.id !== item.id))}>Remove</button>
+  </li>
+)}</ul>
+```
+
+Kudzu emits initial items as static HTML, then adds, removes, updates, and moves keyed elements directly. Existing keys move without remounting, preserving uncontrolled descendant state. Direct `item.<field>` reads use compact markers; derived item expressions compile to external ESM evaluators. Item-local handlers use delegated events and receive the latest JSON-safe item for their key, including after updates, additions, and reorders. The item remains stored once in shared list state; handler descriptors carry a placeholder that the list runtime fills when mounting or updating the keyed root.
+
+Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a direct local-state `.map`, one identifier callback parameter, one intrinsic JSX root, and `key={item.<field>}`. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, locals, imported helpers, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Nested conditions or lists, item spreads, component tags, fragments, and reactive `style`, `ref`, or `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+
 ## Normal JavaScript
 
 Command-only setters use the smallest optimized path. Conditions, local variables, browser globals, events, and `async`/`await` compile to external ESM without `eval`, `new Function`, or inline executable code.
@@ -151,6 +190,8 @@ async function load() {
 
 Primitive values, arrays, plain objects, and destructured props can be captured by client handlers. Functions, symbols, bigints, cycles, class instances, and imported helper functions are not yet supported as captures.
 
+Native handlers are delegated after normal event bubbling and run from the target toward matching Kudzu ancestors in deterministic order. Delegated handlers cannot call or reference `preventDefault`, `stopPropagation`, or `stopImmediatePropagation`; the compiler rejects those methods because external ESM cannot apply them with correct synchronous DOM semantics.
+
 ## Rendering
 
 ```text
@@ -158,6 +199,7 @@ TSX
 ├─ static component      → HTML
 ├─ ordered state setter  → behavior command
 ├─ conditional child     → bounded DOM range
+├─ keyed state map       → keyed DOM moves
 └─ normal JS handler     → external ESM
 ```
 
@@ -185,12 +227,14 @@ Supported:
 - Synchronous and async event handlers
 - Serializable component-local captures
 - Direct text DOM patches
-- Reactive `className`, `disabled`, and controlled `value` patches
+- Reactive standard, `aria-*`, and `data-*` attributes
+- Controlled `value` and `checked` form properties
 - Conditional child `&&` and ternary DOM patches
+- Direct keyed local-state lists
 
 Not implemented yet:
 
-- Keyed lists and generalized JSX-valued locals
+- Generalized JSX-valued locals and non-direct list item expressions
 - Server actions and request-time SSR
 - Imported client helpers and React package islands
 - HMR and framework DevTools
@@ -205,13 +249,13 @@ Same counter with initial value `7` and increment/decrement buttons:
 
 | Framework | Initial content | Initial JS gzip | Total output | Clean build |
 |---|---:|---:|---:|---:|
-| Kudzu | Yes | 487 B | 1.4 KB | **385 ms** |
-| Astro | Yes | **158 B** | **365 B** | 948 ms |
-| Svelte CSR | No | 10.5 KB | 26.9 KB | 885 ms |
-| Qwik CSR | No | 20.6 KB | 57.8 KB | 622 ms |
-| Vue CSR | No | 24.0 KB | 60.3 KB | 822 ms |
-| React CSR | No | 59.2 KB | 189.0 KB | 1084 ms |
-| Next.js | Yes | 182.1 KB | 652.2 KB | 3074 ms |
+| Kudzu | Yes | 487 B | 1.4 KB | **373 ms** |
+| Astro | Yes | **158 B** | **365 B** | 877 ms |
+| Svelte CSR | No | 10.5 KB | 26.9 KB | 837 ms |
+| Qwik CSR | No | 20.6 KB | 57.8 KB | 626 ms |
+| Vue CSR | No | 24.0 KB | 60.3 KB | 778 ms |
+| React CSR | No | 59.2 KB | 189.0 KB | 1049 ms |
+| Next.js | Yes | 182.1 KB | 652.2 KB | 3099 ms |
 
 Astro produces the smallest hand-authored counter. Kudzu's advantage in this fixture is React-shaped state code with a sub-1 KB runtime, not the smallest possible JavaScript.
 

package/framework/README.md

@@ -4,12 +4,13 @@
 - `core.mjs`: server-side JSX rendering, state slots, behavior metadata, and serializable capture validation.
 - `jsx-runtime.mjs`: automatic JSX runtime used by TypeScript.
 - `runtime.js`: command-only runtime for direct state-to-text patches.
-- `shared-runtime.js`: command runtime with binding commit hooks, emitted only when needed.
-- `binding-runtime.js`: optional reactive attributes and conditional DOM range patches.
+- `shared-runtime.js`: command runtime with capability commit and DOM lifecycle hooks, emitted only when needed.
+- `binding-runtime.js`: optional generic attributes, form properties, and conditional range patches.
+- `list-runtime.js`: optional keyed list validation, external item-expression evaluation, dynamic item-handler scopes, moves, and cleanup.
 - `serialization.js`: capture deserialization shared by binding and native handlers.
 - `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes add `binding-runtime.js`; native handlers add `native-runtime.js`. Generated evaluators live under `dist/assets/handlers/`.
+Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators live under `dist/assets/handlers/`.
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/binding-runtime.js

@@ -1,4 +1,4 @@
-import { browserState, mountText, registerCommitter } from "./shared-runtime.js"
+import { browserState, mountDom, registerCommitter, registerMountHook, registerUnmountHook, unmountDom } from "./shared-runtime.js"
 import { deserialize } from "./serialization.js"
 
 const imports = new Map()
@@ -8,17 +8,25 @@ const mountedBindings = new WeakSet()
 const mountedConditions = new WeakSet()
 const bindingRegistrations = new WeakMap()
 const conditionRegistrations = new WeakMap()
+const bindingTypes = ["class", "disabled", "value", "checked"]
+const bindingSelector = [...bindingTypes.map(target => `[data-k-bind-${target}]`), "[data-k-bind-attrs]"].join(",")
 
 export function patchBinding(node, target, value) {
   if (target === "disabled") {
     node.toggleAttribute("disabled", Boolean(value))
+  } else if (target === "checked") {
+    node.checked = Boolean(value)
   } else if (target === "value") {
     const next = value == null ? "" : String(value)
     if (node.value !== next) node.value = next
-  } else if (value == null || value === false) {
+  } else if (target === "class" && (value == null || value === false)) {
     node.removeAttribute("class")
-  } else {
+  } else if (target === "class") {
     node.setAttribute("class", String(value))
+  } else if (value == null || (value === false && !isStringBooleanAttribute(target))) {
+    node.removeAttribute(target)
+  } else {
+    node.setAttribute(target, value === true && !isStringBooleanAttribute(target) ? "" : String(value))
   }
 }
 
@@ -42,37 +50,38 @@ function commitConditions(id) {
 
 registerCommitter(commitBindings)
 registerCommitter(commitConditions)
+registerMountHook(mountBindings)
+registerMountHook(mountConditions)
+registerUnmountHook(unmountBindings)
+registerUnmountHook(unmountConditions)
 
 if (typeof document !== "undefined") mountDom(document)
 
-function mountDom(root) {
-  mountText(root)
-  mountBindings(root)
-  mountConditions(root)
-}
-
 function mountBindings(root) {
-  for (const target of ["class", "disabled", "value"]) {
-    for (const node of matching(root, `[data-k-bind-${target}]`)) {
-      if (mountedBindings.has(node)) continue
-      mountedBindings.add(node)
-      const descriptor = JSON.parse(node.dataset[`kBind${capitalize(target)}`])
+  for (const node of matching(root, bindingSelector)) {
+    if (mountedBindings.has(node)) continue
+    mountedBindings.add(node)
+    const registrations = []
+    bindingRegistrations.set(node, registrations)
+    const descriptors = bindingTypes.flatMap(target => node.hasAttribute(`data-k-bind-${target}`)
+      ? [[target, JSON.parse(node.dataset[`kBind${capitalize(target)}`])]]
+      : [])
+    if (node.dataset.kBindAttrs) descriptors.push(...JSON.parse(node.dataset.kBindAttrs).map(({ target, ...descriptor }) => [target, descriptor]))
+    for (const [target, descriptor] of descriptors) {
       if (descriptor.state) {
         const binding = { node, target, read: () => browserState.get(descriptor.state) }
         register(bindingTargets, descriptor.state, binding)
-        bindingRegistrations.set(node, [[descriptor.state, binding]])
+        registrations.push([descriptor.state, binding])
         patchBinding(node, target, binding.read())
         continue
       }
       loadEvaluator(descriptor).then(evaluator => {
         if (!node.isConnected) return
         const binding = { node, target, read: evaluator.read }
-        const registrations = []
         for (const id of evaluator.stateIds) {
           register(bindingTargets, id, binding)
           registrations.push([id, binding])
         }
-        bindingRegistrations.set(node, registrations)
         patchBinding(node, target, binding.read())
       }).catch(error => console.error(error))
     }
@@ -117,14 +126,21 @@ function updateCondition(condition) {
   condition.end.parentNode.insertBefore(fragment, condition.end)
   condition.current = next
   for (const node of nodes) mountDom(node)
+  const select = condition.start.closest("select[data-k-bind-value]")
+  for (const binding of new Set((bindingRegistrations.get(select) ?? []).map(([, entry]) => entry))) {
+    patchBinding(binding.node, binding.target, binding.read())
+  }
 }
 
-function unmountDom(root) {
-  for (const node of matching(root, "[data-k-bind-class],[data-k-bind-disabled],[data-k-bind-value]")) {
+function unmountBindings(root) {
+  for (const node of matching(root, bindingSelector)) {
     for (const [id, binding] of bindingRegistrations.get(node) ?? []) bindingTargets.get(id)?.delete(binding)
     bindingRegistrations.delete(node)
     mountedBindings.delete(node)
   }
+}
+
+function unmountConditions(root) {
   for (const start of matching(root, "template[data-k-if]")) {
     const registration = conditionRegistrations.get(start)
     for (const [id, condition] of registration?.registrations ?? []) conditionTargets.get(id)?.delete(condition)
@@ -138,9 +154,8 @@ function removeConditionRange(start, end) {
   range.setStartAfter(start)
   range.setEndBefore(end)
   const root = range.commonAncestorContainer
-  for (const node of matching(root, "[data-k-bind-class],[data-k-bind-disabled],[data-k-bind-value],template[data-k-if]")) {
-    if (range.comparePoint(node, 0) === 0) unmountDom(node)
-  }
+  const nodes = matching(root, "*").filter(node => range.comparePoint(node, 0) === 0)
+  for (const node of nodes) if (!nodes.some(parent => parent !== node && parent.contains(node))) unmountDom(node)
   range.deleteContents()
 }
 
@@ -207,3 +222,7 @@ function matching(root, selector) {
 function capitalize(value) {
   return value[0].toUpperCase() + value.slice(1)
 }
+
+function isStringBooleanAttribute(name) {
+  return name.startsWith("aria-") || name.startsWith("data-")
+}