@kudzujs/core 0.4.0 → 0.4.1

package/README.md

@@ -150,16 +150,25 @@ Map local array state directly to one keyed JSX element per item:
 
 ```tsx
 const [items, setItems] = useState([
-  { id: 1, name: "Oak" },
-  { id: 2, name: "Pine" }
+  { id: 1, name: "Oak", done: false },
+  { id: 2, name: "Pine", done: true }
 ])
 
-<ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>
+<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. Each item must be a plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, plain objects, and primitive values.
+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.
 
-The MVP requires a direct local-state `.map`, one identifier callback parameter, one intrinsic JSX root, and `key={item.<field>}`. Item data may appear only as direct `item.<field>` text or attributes. Item-derived expressions, item-local handlers, nested conditions or lists, component tags, and fragments are rejected at build time. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+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
 
@@ -181,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

package/framework/README.md

@@ -6,7 +6,7 @@
 - `runtime.js`: command-only runtime for direct state-to-text 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, updates, moves, and cleanup.
+- `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.

package/framework/build.mjs

@@ -150,6 +150,7 @@ async function compile(file) {
   const source = await readFile(file, "utf8")
   const nativeHandlers = []
   const reactiveBindings = []
+  const listExpressions = []
   const handlerPath = `handlers/${relative(sourceDirectory, file).replaceAll(sep, "/").replace(/\.(?:ts|tsx)$/, ".js")}`
   const result = ts.transpileModule(source, {
     fileName: file,
@@ -159,7 +160,7 @@ async function compile(file) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, `/assets/${handlerPath}`)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, `/assets/${handlerPath}`)] },
     reportDiagnostics: true
   })
 
@@ -172,10 +173,11 @@ async function compile(file) {
   await mkdir(resolve(output, ".."), { recursive: true })
   await writeFile(output, result.outputText)
 
-  if (!nativeHandlers.length && !reactiveBindings.length) return undefined
+  if (!nativeHandlers.length && !reactiveBindings.length && !listExpressions.length) return undefined
   const moduleSource = [
     ...nativeHandlers.map(handler => printNativeHandler(handler)),
-    ...reactiveBindings.map(entry => printReactiveBinding(entry))
+    ...reactiveBindings.map(entry => printReactiveBinding(entry)),
+    ...listExpressions.map(entry => printListExpression(entry))
   ].join("\n")
   const moduleResult = ts.transpileModule(moduleSource, {
     compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext },
@@ -186,12 +188,13 @@ async function compile(file) {
   return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0 }
 }
 
-function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
+function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, handlerUrl) {
   return context => sourceFile => {
     const factory = context.factory
     const settersByFunction = new Map()
     const functions = new Map()
-    const listFieldExpressions = new WeakSet()
+    const listValues = new WeakMap()
+    const listEventItems = new WeakMap()
     let usesBehavior = false
     let usesBinding = false
     let usesConditional = false
@@ -237,13 +240,20 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
         return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, initializer)
       }
 
+      if (ts.isJsxExpression(node) && node.expression && listValues.has(node.expression)) {
+        return factory.updateJsxExpression(node, compileListValue(node.expression, listValues.get(node.expression), factory, listExpressions, handlerUrl))
+      }
+
+      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && listValues.has(node.initializer.expression)) {
+        return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, compileListValue(node.initializer.expression, listValues.get(node.initializer.expression), factory, listExpressions, handlerUrl)))
+      }
+
       if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
         const listParts = keyedListParts(node.expression, settersForNode(node, settersByFunction))
         if (listParts) {
           if (keyedListParentTag(node) === "table") throw new Error("Keyed table rows must be wrapped in <tbody>, <thead>, or <tfoot>")
-          validateKeyedList(listParts, sourceFile, listFieldExpressions)
+          validateKeyedList(listParts, sourceFile, settersForNode(node, settersByFunction), listValues, listEventItems)
           usesBehavior = true
-          usesBinding = true
           usesList = true
           return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
             listParts.state,
@@ -269,7 +279,6 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
 
       if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && !/^on/i.test(node.name.getText()) && !["style", "key", "ref", "dangerouslysetinnerhtml"].includes(node.name.getText().toLowerCase())) {
         const expression = node.initializer.expression
-        if (listFieldExpressions.has(expression)) return node
         const setters = settersForNode(node, settersByFunction)
         const usedStates = referencedStateNames(expression, setters)
         const captures = captureNames(expression, expression, setters)
@@ -283,7 +292,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
 
       if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && /^on[A-Z]/.test(node.name.getText())) {
         const setters = settersForNode(node, settersByFunction)
-        const event = compileEvent(node.initializer.expression, setters, functions, factory, nativeHandlers, handlerUrl)
+        const event = compileEvent(node.initializer.expression, setters, functions, factory, nativeHandlers, handlerUrl, listEventItems.get(node))
         if (event) {
           usesBehavior = true
           return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, event))
@@ -302,7 +311,12 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
     if (nativeHandlers.length) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("nativeBehavior"), factory.createIdentifier("__kNativeBehavior")))
     if (usesBinding) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("binding"), factory.createIdentifier("__kBinding")))
     if (usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("conditional"), factory.createIdentifier("__kConditional")))
-    if (usesList) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("list"), factory.createIdentifier("__kList")))
+    if (usesList) {
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("list"), factory.createIdentifier("__kList")))
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listExpression"), factory.createIdentifier("__kListExpression")))
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listField"), factory.createIdentifier("__kListField")))
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listItem"), factory.createIdentifier("__kListItem")))
+    }
     if (usesBinding || usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
       undefined,
@@ -331,7 +345,7 @@ function keyedListParts(expression, setters) {
   return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
 }
 
-function validateKeyedList(parts, sourceFile, listFieldExpressions) {
+function validateKeyedList(parts, sourceFile, setters, listValues, listEventItems) {
   const fail = (node, message) => {
     const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
@@ -341,27 +355,112 @@ function validateKeyedList(parts, sourceFile, listFieldExpressions) {
     if (!ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) fail(node, "Keyed list items must use intrinsic JSX elements")
   }
   const visit = node => {
+    if (ts.isJsxFragment(node)) fail(node, "Fragments are not supported in keyed lists")
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) validateElement(node)
-    if (node !== parts.root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map") fail(node, "Nested keyed lists are not supported")
+    if (node !== parts.root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, "Nested keyed lists are not supported")
     if (ts.isJsxSpreadAttribute(node) && referencesIdentifier(node.expression, parts.item)) fail(node, "Keyed list item spreads are not supported")
-    if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.getText())) fail(node, "Item-local handlers are not supported in keyed lists")
+    if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.getText())) {
+      listEventItems.set(node, parts.item)
+      return
+    }
     if (ts.isJsxExpression(node) && node.expression) {
       const expression = unwrapExpression(node.expression)
+      if (conditionalParts(expression) && containsJsx(expression)) fail(node, "Nested reactive conditions are not supported in keyed lists")
       const field = directProperty(expression, parts.item)
-      const isRootKey = node.parent?.parent === parts.root && ts.isJsxAttribute(node.parent) && node.parent.name.getText() === "key"
+      const isRootKey = ts.isJsxAttribute(node.parent) && node.parent.name.getText() === "key"
+      if (field && ["__proto__", "constructor", "prototype"].includes(field)) fail(node, `Keyed list item property "${field}" is not supported`)
       if (field && ts.isJsxAttribute(node.parent) && ["style", "ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
-      if (isRootKey || field) {
-        if (field) listFieldExpressions.add(node.expression)
+      if (isRootKey) return
+      if (field) {
+        listValues.set(node.expression, { field })
+        return
+      }
+      if (referencesIdentifier(expression, parts.item)) {
+        validateListExpression(expression, parts.item, node, fail)
+        if (ts.isJsxAttribute(node.parent) && ["style", "ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
+        listValues.set(node.expression, { item: parts.item })
         return
       }
-      if (conditionalParts(expression)) fail(node, "Nested reactive conditions are not supported in keyed lists")
-      if (referencesIdentifier(expression, parts.item)) fail(node, `Keyed list item expressions must be direct ${parts.item}.<field> reads`)
     }
     ts.forEachChild(node, visit)
   }
   visit(parts.root)
 }
 
+const pureListMethods = new Set(["at", "charAt", "charCodeAt", "concat", "endsWith", "includes", "indexOf", "join", "lastIndexOf", "padEnd", "padStart", "repeat", "replace", "replaceAll", "slice", "startsWith", "substring", "toLowerCase", "toUpperCase", "trim", "trimEnd", "trimStart"])
+const mutatingListMethods = new Set(["copyWithin", "fill", "pop", "push", "reverse", "shift", "sort", "splice", "unshift"])
+const pureMathMethods = new Set(["abs", "ceil", "floor", "max", "min", "pow", "round", "sign", "sqrt", "trunc"])
+const pureListGlobals = new Set(["Boolean", "Infinity", "Math", "NaN", "Number", "String", "undefined"])
+const assignmentOperators = new Set([
+  ts.SyntaxKind.EqualsToken, ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.MinusEqualsToken,
+  ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskAsteriskEqualsToken, ts.SyntaxKind.SlashEqualsToken,
+  ts.SyntaxKind.PercentEqualsToken, ts.SyntaxKind.LessThanLessThanEqualsToken, ts.SyntaxKind.GreaterThanGreaterThanEqualsToken,
+  ts.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken, ts.SyntaxKind.AmpersandEqualsToken, ts.SyntaxKind.BarEqualsToken,
+  ts.SyntaxKind.CaretEqualsToken, ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.AmpersandAmpersandEqualsToken,
+  ts.SyntaxKind.QuestionQuestionEqualsToken
+])
+
+function validateListExpression(expression, item, source, fail) {
+  const visit = node => {
+    if (ts.isElementAccessExpression(node) && referencesIdentifier(node.expression, item)) {
+      const key = node.argumentExpression
+      if (!ts.isStringLiteral(key) && !ts.isNumericLiteral(key)) fail(source, "Derived keyed list item computed properties require a direct string or numeric literal key")
+      if (ts.isStringLiteral(key) && ["__proto__", "constructor", "prototype"].includes(key.text)) fail(source, `Derived keyed list item property "${key.text}" is not supported`)
+    }
+    if (ts.isPropertyAccessExpression(node) && ["__proto__", "constructor", "prototype"].includes(node.name.text) || ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression) && ["__proto__", "constructor", "prototype"].includes(node.argumentExpression.text)) {
+      fail(source, "Derived keyed list item expressions cannot read __proto__, prototype, or constructor")
+    }
+    if (ts.isBinaryExpression(node) && assignmentOperators.has(node.operatorToken.kind) || ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator)) {
+      fail(source, "Derived keyed list item expressions must be pure; assignments and updates are not supported")
+    }
+    if (ts.isDeleteExpression(node) || ts.isAwaitExpression(node) || ts.isNewExpression(node) || ts.isYieldExpression(node)) {
+      fail(source, "Derived keyed list item expressions must be synchronous and side-effect free; delete, await, yield, and new are not supported")
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isTaggedTemplateExpression(node)) {
+      fail(source, "Derived keyed list item expressions cannot create or invoke arbitrary functions")
+    }
+    if (ts.isCallExpression(node)) {
+      if (ts.isPropertyAccessExpression(node.expression)) {
+        const method = node.expression.name.text
+        if (mutatingListMethods.has(method)) fail(source, `Derived keyed list item expressions cannot call mutating method "${method}"`)
+        const receiver = node.expression.expression
+        const mathCall = ts.isIdentifier(receiver) && receiver.text === "Math" && pureMathMethods.has(method)
+        if (!mathCall && !pureListMethods.has(method)) fail(source, `Derived keyed list item expressions cannot call arbitrary method "${method}"`)
+      } else if (!ts.isIdentifier(node.expression) || !["Boolean", "Number", "String"].includes(node.expression.text)) {
+        fail(source, "Derived keyed list item expressions cannot call arbitrary functions")
+      }
+    }
+    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && node.text !== item && !pureListGlobals.has(node.text)) {
+      fail(source, `Derived keyed list item expression identifier "${node.text}" is not allowed`)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(expression)
+}
+
+function containsJsx(root) {
+  let found = false
+  const visit = node => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) found = true
+    if (!found) ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return found
+}
+
+function compileListExpression(read, expression, item, factory, listExpressions, handlerUrl) {
+  const exportName = `listExpression${listExpressions.length}`
+  listExpressions.push({ exportName, expression, item })
+  return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)])
+}
+
+function compileListValue(expression, entry, factory, listExpressions, handlerUrl) {
+  const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), expression)
+  return entry.field
+    ? factory.createCallExpression(factory.createIdentifier("__kListField"), undefined, [read, factory.createStringLiteral(entry.field)])
+    : compileListExpression(read, expression, entry.item, factory, listExpressions, handlerUrl)
+}
+
 function directProperty(expression, objectName) {
   const value = unwrapExpression(expression)
   if (!ts.isPropertyAccessExpression(value) || !ts.isIdentifier(value.expression)) return undefined
@@ -454,10 +553,11 @@ function factoryNull() {
   return ts.factory.createNull()
 }
 
-function compileEvent(expression, setters, functions, factory, nativeHandlers, handlerUrl) {
+function compileEvent(expression, setters, functions, factory, nativeHandlers, handlerUrl, listItem) {
   if (ts.isIdentifier(expression)) expression = functions.get(expression.text)
   if (!expression || (!ts.isArrowFunction(expression) && !ts.isFunctionExpression(expression) && !ts.isFunctionDeclaration(expression))) return undefined
 
+  rejectNativeEventControls(expression)
   const optimized = compileOptimizedEvent(expression, setters, factory)
   if (optimized) return optimized
 
@@ -469,18 +569,45 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
     factory.createStringLiteral(name),
     factory.createIdentifier(name)
   ]))
-  const scope = [...captures].map(name => factory.createArrayLiteralExpression([
-    factory.createStringLiteral(name),
-    factory.createIdentifier(name)
-  ]))
   return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
     factory.createStringLiteral(handlerUrl),
     factory.createStringLiteral(exportName),
     factory.createArrayLiteralExpression(states),
-    factory.createArrayLiteralExpression(scope)
+    factory.createArrayLiteralExpression([...captures].map(name => factory.createArrayLiteralExpression([
+      factory.createStringLiteral(name),
+      name === listItem ? factory.createCallExpression(factory.createIdentifier("__kListItem"), undefined, []) : factory.createIdentifier(name)
+    ])))
   ])
 }
 
+function rejectNativeEventControls(expression) {
+  const controls = new Set(["preventDefault", "stopPropagation", "stopImmediatePropagation"])
+  const found = new Set()
+  const eventAliases = new Set()
+  const parameter = expression.parameters[0]?.name
+  if (parameter && ts.isIdentifier(parameter)) eventAliases.add(parameter.text)
+  const visit = node => {
+    if (ts.isIdentifier(node) && controls.has(node.text)) found.add(node.text)
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isIdentifier(unwrapEventAlias(node.initializer)) && eventAliases.has(unwrapEventAlias(node.initializer).text)) {
+      eventAliases.add(node.name.text)
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(node.left) && ts.isIdentifier(unwrapEventAlias(node.right)) && eventAliases.has(unwrapEventAlias(node.right).text)) eventAliases.add(node.left.text)
+    if (ts.isElementAccessExpression(node) && ts.isIdentifier(unwrapEventAlias(node.expression)) && eventAliases.has(unwrapEventAlias(node.expression).text)) {
+      if (ts.isStringLiteral(node.argumentExpression) && controls.has(node.argumentExpression.text)) found.add(node.argumentExpression.text)
+      else if (!ts.isStringLiteral(node.argumentExpression)) for (const control of controls) found.add(control)
+    }
+    ts.forEachChild(node, visit)
+  }
+  for (const parameter of expression.parameters) visit(parameter)
+  visit(expression.body)
+  if (found.size) throw new Error(`Delegated native handlers do not support event control methods: ${[...found].sort().join(", ")}`)
+}
+
+function unwrapEventAlias(node) {
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node)) return unwrapEventAlias(node.expression)
+  return node
+}
+
 function nativeStateNames(expression, setters) {
   return referencedStateNames(expression.body, setters, expression)
 }
@@ -681,6 +808,19 @@ function printReactiveBinding({ exportName, expression, captures, states }) {
   }
 }
 
+function printListExpression({ exportName, expression, item }) {
+  const declaration = ts.factory.createFunctionDeclaration(
+    [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    undefined,
+    exportName,
+    undefined,
+    [ts.factory.createParameterDeclaration(undefined, undefined, item)],
+    undefined,
+    ts.factory.createBlock([ts.factory.createReturnStatement(expression)], true)
+  )
+  return ts.createPrinter().printNode(ts.EmitHint.Unspecified, declaration, expression.getSourceFile())
+}
+
 function scopeRead(factory, name) {
   return factory.createCallExpression(
     factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "scope"),

package/framework/core.d.ts

@@ -8,6 +8,9 @@ export function binding(value: unknown, module: string, handler: string, states:
 export function bindingValue(value: unknown): unknown
 export function conditional(kind: "and" | "ternary", value: unknown, truthy: () => unknown, falsy: () => unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
 export function list(items: unknown, keyField: string, render: (item: unknown) => unknown): unknown
+export function listField(read: () => unknown, field: string): unknown
+export function listExpression(read: () => unknown, module: string, handler: string): unknown
+export function listItem(): unknown
 
 export function renderPage(
   component: (props: Record<string, never>) => unknown | Promise<unknown>,

package/framework/core.mjs

@@ -5,6 +5,8 @@ const bindingMarker = Symbol("kudzu.binding")
 const conditionalMarker = Symbol("kudzu.conditional")
 const listMarker = Symbol("kudzu.list")
 const listFieldMarker = Symbol("kudzu.listField")
+const listExpressionMarker = Symbol("kudzu.listExpression")
+const listItemMarker = Symbol("kudzu.listItem")
 const noSelectValue = Symbol("kudzu.no-select-value")
 
 let renderContext
@@ -79,13 +81,27 @@ export function list(items, keyField, render) {
   return { [listMarker]: true, items, keyField, render }
 }
 
+export function listField(read, field) {
+  return { [listFieldMarker]: true, field, value: renderContext?.listTemplate ? undefined : read() }
+}
+
+export function listExpression(read, module, handler) {
+  const value = renderContext?.listTemplate ? undefined : read()
+  if (value && typeof value.then === "function") throw new Error("Derived keyed list item expressions must return synchronous values")
+  return { [listExpressionMarker]: true, module, handler, value }
+}
+
+export function listItem() {
+  return { [listItemMarker]: true }
+}
+
 function validListKey(key) {
   return typeof key === "string" || typeof key === "number" && Number.isFinite(key)
 }
 
 function assertListItem(item) {
   const prototype = item && typeof item === "object" ? Object.getPrototypeOf(item) : undefined
-  if (!item || Array.isArray(item) || prototype !== Object.prototype && prototype !== null) throw new Error("Keyed list items must be plain objects")
+  if (!item || Array.isArray(item) || prototype !== Object.prototype) throw new Error("Keyed list items must be ordinary plain objects")
 }
 
 function assertListValue(value, seen) {
@@ -93,7 +109,7 @@ function assertListValue(value, seen) {
   if (!value || typeof value !== "object") throw new Error(`Keyed list items must contain only JSON-safe values`)
   if (seen.has(value)) throw new Error("Keyed list items must not contain cycles")
   const prototype = Object.getPrototypeOf(value)
-  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) throw new Error("Keyed list items must contain only arrays and plain objects")
+  if (!Array.isArray(value) && prototype !== Object.prototype) throw new Error("Keyed list items must contain only arrays and ordinary plain objects")
   if (Object.getOwnPropertySymbols(value).length) throw new Error("Keyed list items must not contain symbols")
   seen.add(value)
   const descriptors = Object.getOwnPropertyDescriptors(value)
@@ -139,6 +155,7 @@ function bindingDescriptor(value) {
 }
 
 function serializeCapture(name, value, seen) {
+  if (value?.[listItemMarker]) return { type: "list-item" }
   if (value === null || typeof value === "string" || typeof value === "boolean") return value
   if (typeof value === "number") {
     return Number.isFinite(value) && !Object.is(value, -0) ? value : { type: "number", value: String(value) }
@@ -170,7 +187,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}) {
-  renderContext = { nextState: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false }
+  renderContext = { nextState: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false }
 
   try {
     const body = await renderNode({ type: component, props: {} })
@@ -290,6 +307,10 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (node?.[listFieldMarker]) {
     return `<template data-k-list-text="${escapeAttribute(node.field)}"></template>${escapeHtml(node.value ?? "")}<template data-k-list-text-end></template>`
   }
+  if (node?.[listExpressionMarker]) {
+    const descriptor = { module: node.module, handler: node.handler }
+    return `<template data-k-list-expression='${escapeJsonAttribute(descriptor)}'></template>${escapeHtml(node.value ?? "")}<template data-k-list-expression-end></template>`
+  }
   if (!node || typeof node !== "object" || !("type" in node)) {
     throw new Error(`Cannot render ${String(node)}`)
   }
@@ -308,6 +329,8 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   let attributes = ""
   const attributeBindings = []
   const listAttributes = []
+  const listExpressionAttributes = []
+  const listEvents = []
 
   if (renderContext.listRoot) {
     const root = renderContext.listRoot
@@ -327,15 +350,17 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     }
 
     if (/^on[A-Z]/.test(rawName)) {
-      const event = rawName.slice(2).toLowerCase()
+        const event = rawName.slice(2).toLowerCase()
       if (value?.[behaviorMarker]) {
         const commands = JSON.stringify(value.commands)
         attributes += ` data-k-on-${event}='${escapeJsonAttribute(value.commands)}'`
         renderContext.events.push({ event, commands: value.commands })
       } else if (value?.[nativeBehaviorMarker]) {
-        const native = { module: value.module, handler: value.handler, states: value.states, scope: value.scope }
+        const template = { module: value.module, handler: value.handler, states: value.states, scope: value.scope }
+        const native = template
         attributes += ` data-k-native-${event}='${escapeJsonAttribute(native)}'`
         renderContext.events.push({ event, native })
+        if (renderContext.listDepth && Object.values(template.scope).some(entry => entry?.type === "list-item")) listEvents.push([event, template])
         renderContext.hasNativeBehaviors = true
       } else {
         throw new Error(`${rawName} must reference a compilable event handler`)
@@ -351,6 +376,11 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
       listAttributes.push([name, value.field])
       continue
     }
+    if (value?.[listExpressionMarker]) {
+      attributes += renderAttribute(name, value.value)
+      listExpressionAttributes.push([name, value.module, value.handler])
+      continue
+    }
     if (value?.[signalMarker] || value?.[bindingMarker]) {
       const initialValue = value[signalMarker] ? value.value : value.value
       const reactive = value[signalMarker] || Object.keys(value.states).length > 0 || Object.keys(value.scopeStates).length > 0 || Object.keys(value.scopeBindings).length > 0
@@ -382,6 +412,8 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
 
   if (attributeBindings.length) attributes += ` data-k-bind-attrs='${escapeJsonAttribute(attributeBindings)}'`
   if (listAttributes.length) attributes += ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
+  if (listExpressionAttributes.length) attributes += ` data-k-list-expression-attrs='${escapeJsonAttribute(listExpressionAttributes)}'`
+  if (listEvents.length) attributes += ` data-k-list-events='${escapeJsonAttribute(listEvents)}'`
 
   if (tag === "option" && selectValue !== noSelectValue && String(optionValue(props)) === (selectValue == null ? "" : String(selectValue))) attributes += " selected"
 
@@ -394,17 +426,16 @@ async function renderList(node, namespace, selectValue) {
   if (namespace) throw new Error(`Reactive keyed lists are not supported inside ${namespace}`)
   const id = `l${renderContext.nextList++}`
   const descriptor = { id, state: node.items.id, key: node.keyField }
-  const itemProxy = value => new Proxy({}, {
-    get: (_, field) => ({ [listFieldMarker]: true, field: String(field), value: value?.[field] })
-  })
   renderContext.listDepth++
   try {
+    renderContext.listTemplate = true
     renderContext.listRoot = { id, template: true }
-    const template = await renderNode(node.render(itemProxy(undefined)), namespace, selectValue)
+    const template = await renderNode(node.render({}), namespace, selectValue)
     let current = ""
+    renderContext.listTemplate = false
     for (const item of node.items.value) {
       renderContext.listRoot = { id, key: item[node.keyField], template: false }
-      current += await renderNode(node.render(itemProxy(item)), namespace, selectValue)
+      current += await renderNode(node.render(item), namespace, selectValue)
     }
     renderContext.lists.push(descriptor)
     renderContext.hasBehaviors = true
@@ -412,6 +443,7 @@ async function renderList(node, namespace, selectValue) {
     return `<template data-k-list='${escapeJsonAttribute(descriptor)}'>${template}</template>${current}<template data-k-list-end="${id}"></template>`
   } finally {
     renderContext.listRoot = undefined
+    renderContext.listTemplate = false
     renderContext.listDepth--
   }
 }

package/framework/list-runtime.js

@@ -3,6 +3,8 @@ import { browserState, mountDom, registerCommitter, registerMountHook, registerU
 const listTargets = new Map()
 const listRegistrations = new WeakMap()
 const mountedLists = new WeakSet()
+const imports = new Map()
+const revisions = new WeakMap()
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -97,20 +99,62 @@ function updateList(list) {
 }
 
 function fillListItem(root, item) {
+  const revision = (revisions.get(root) ?? 0) + 1
+  revisions.set(root, revision)
   for (const marker of matching(root, "template[data-k-list-text]")) {
-    const value = item?.[marker.dataset.kListText]
-    let end = marker.nextSibling
-    while (end && !(end.nodeType === Node.ELEMENT_NODE && end.matches("template[data-k-list-text-end]"))) end = end.nextSibling
-    if (!end) throw new Error("Keyed list text marker has no end")
-    const range = marker.ownerDocument.createRange()
-    range.setStartAfter(marker)
-    range.setEndBefore(end)
-    range.deleteContents()
-    end.before(marker.ownerDocument.createTextNode(value == null ? "" : String(value)))
+    patchListText(marker, "template[data-k-list-text-end]", item?.[marker.dataset.kListText])
   }
   for (const node of matching(root, "[data-k-list-attrs]")) {
     for (const [target, field] of JSON.parse(node.dataset.kListAttrs)) patchBinding(node, target, item?.[field])
   }
+  for (const node of matching(root, "[data-k-list-events]")) {
+    for (const [event, native] of JSON.parse(node.dataset.kListEvents)) {
+      native.scope = Object.fromEntries(Object.entries(native.scope).map(([name, value]) => [name, value?.type === "list-item" ? serializeItem(item) : value]))
+      node.dataset[`kNative${capitalize(event)}`] = JSON.stringify(native)
+    }
+  }
+  for (const marker of matching(root, "template[data-k-list-expression]")) {
+    evaluate(JSON.parse(marker.dataset.kListExpression), item).then(value => {
+      if (revisions.get(root) === revision && root.isConnected) patchListText(marker, "template[data-k-list-expression-end]", value)
+    }).catch(error => console.error(error))
+  }
+  for (const node of matching(root, "[data-k-list-expression-attrs]")) {
+    for (const [target, module, handler] of JSON.parse(node.dataset.kListExpressionAttrs)) {
+      evaluate({ module, handler }, item).then(value => {
+        if (revisions.get(root) === revision && root.isConnected) patchBinding(node, target, value)
+      }).catch(error => console.error(error))
+    }
+  }
+}
+
+function patchListText(marker, endSelector, value) {
+  let end = marker.nextSibling
+  while (end && !(end.nodeType === Node.ELEMENT_NODE && end.matches(endSelector))) end = end.nextSibling
+  if (!end) throw new Error("Keyed list text marker has no end")
+  const range = marker.ownerDocument.createRange()
+  range.setStartAfter(marker)
+  range.setEndBefore(end)
+  range.deleteContents()
+  end.before(marker.ownerDocument.createTextNode(value == null ? "" : String(value)))
+}
+
+function evaluate(descriptor, item) {
+  let module = imports.get(descriptor.module)
+  if (!module) {
+    module = import(descriptor.module)
+    imports.set(descriptor.module, module)
+  }
+  return module.then(exports => {
+    const value = exports[descriptor.handler](item)
+    if (value && typeof value.then === "function") throw new Error("Derived keyed list item expressions must return synchronous values")
+    return value
+  })
+}
+
+function serializeItem(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") return value
+  if (Array.isArray(value)) return { type: "array", value: value.map(serializeItem) }
+  return { type: "object", nullPrototype: false, value: Object.entries(value).map(([key, entry]) => [key, serializeItem(entry)]) }
 }
 
 function patchBinding(node, target, value) {
@@ -142,7 +186,7 @@ function validListKey(key) {
 
 function assertListItem(item) {
   const prototype = item && typeof item === "object" ? Object.getPrototypeOf(item) : undefined
-  if (!item || Array.isArray(item) || prototype !== Object.prototype && prototype !== null) throw new Error("Keyed list items must be plain objects")
+  if (!item || Array.isArray(item) || prototype !== Object.prototype) throw new Error("Keyed list items must be ordinary plain objects")
 }
 
 function assertListValue(value, seen) {
@@ -150,7 +194,7 @@ function assertListValue(value, seen) {
   if (!value || typeof value !== "object") throw new Error("Keyed list items must contain only JSON-safe values")
   if (seen.has(value)) throw new Error("Keyed list items must not contain cycles")
   const prototype = Object.getPrototypeOf(value)
-  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) throw new Error("Keyed list items must contain only arrays and plain objects")
+  if (!Array.isArray(value) && prototype !== Object.prototype) throw new Error("Keyed list items must contain only arrays and ordinary plain objects")
   if (Object.getOwnPropertySymbols(value).length) throw new Error("Keyed list items must not contain symbols")
   seen.add(value)
   const descriptors = Object.getOwnPropertyDescriptors(value)
@@ -183,3 +227,7 @@ function matching(root, selector) {
 function isStringBooleanAttribute(name) {
   return name.startsWith("aria-") || name.startsWith("data-")
 }
+
+function capitalize(value) {
+  return value[0].toUpperCase() + value.slice(1)
+}

package/framework/native-runtime.js

@@ -39,19 +39,38 @@ if (typeof document !== "undefined") {
   const eventNames = ["click", "input", "change", "submit", "keydown", "keyup"]
   for (const eventName of eventNames) {
     document.addEventListener(eventName, event => {
-      const target = event.target.closest(`[data-k-native-${eventName}]`)
-      if (!target) return
-
-      const native = JSON.parse(target.dataset[`kNative${capitalize(eventName)}`])
-      let modulePromise = modules.get(native.module)
-      if (!modulePromise) {
-        modulePromise = import(native.module)
-        modules.set(native.module, modulePromise)
+      try {
+        dispatchNative(event, snapshotNativeTargets(event, eventName), modules).catch(error => console.error(error))
+      } catch (error) {
+        console.error(error)
       }
-      modulePromise
-        .then(module => module[native.handler](createNativeContext(browserState, native.states, commitDom, native.scope), delegatedEvent(event, target)))
-        .catch(error => console.error(error))
-    }, true)
+    })
+  }
+}
+
+function snapshotNativeTargets(event, eventName) {
+  const selector = `[data-k-native-${eventName}]`
+  const targets = []
+  for (let target = event.target.closest(selector); target; target = target.parentElement?.closest(selector)) {
+    targets.push({ target, native: JSON.parse(target.dataset[`kNative${capitalize(eventName)}`]) })
+  }
+  return targets
+}
+
+async function dispatchNative(event, targets, modules) {
+  for (const { target, native } of targets) {
+    let modulePromise = modules.get(native.module)
+    if (!modulePromise) {
+      modulePromise = import(native.module)
+      modules.set(native.module, modulePromise)
+    }
+    try {
+      const module = await modulePromise
+      const result = module[native.handler](createNativeContext(browserState, native.states, commitDom, native.scope), delegatedEvent(event, target))
+      if (result && typeof result.then === "function") result.catch(error => console.error(error))
+    } catch (error) {
+      console.error(error)
+    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",