@kudzujs/core 0.8.5 → 0.8.7

package/README.md

@@ -10,7 +10,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.5 - Owned timer actions.** A directly returned relative custom-hook callback may own one private timeout ref with latest-only replacement and effect cleanup, without adding a timer runtime. Read the [release notes](./RELEASES.md#085---owned-timer-actions) or open the [release page](https://kudzujs.cloud/releases/0.8.5).
+**Latest release: 0.8.7 - Reactive keyed row selection.** Flat keyed rows may combine their current item or index with direct primitive parent state in pure text and attribute expressions, enabling selected classes and ARIA state without remounting rows. Read the [release notes](./RELEASES.md#087---reactive-keyed-row-selection) or open the [release page](https://kudzujs.cloud/releases/0.8.7).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,51 @@
 # Kudzu Releases
 
+## 0.8.7 - Reactive keyed row selection
+
+Kudzu 0.8.7 lets a flat keyed row combine its current item or index with direct primitive parent state in pure text and attribute expressions.
+
+### New in 0.8.7
+
+- Selected-row classes, `aria-current`, `aria-selected`, and similar pure expressions update directly after parent-state commits.
+- Retained rows reevaluate only their expression text and attributes; list structure, handlers, and DOM identity remain untouched.
+- Initial static HTML evaluates the same expression with build-time state values.
+- Calculated SVG coverage verifies focus, Space, click, insertion, reorder, latest handlers, selected classes, ARIA state, and retained node identity.
+- A React Notes migration restores its ordinary `activeId === note.id` selected-row source without imperative DOM code.
+- Object/array parent state, arbitrary captures, nested-row parent state, structural conditions, mutation, and arbitrary calls remain diagnosed.
+- The complete suite passes 134/134 tests.
+
+### Boundary
+
+This support is limited to pure flat keyed-row text and attribute expressions over the current item/index plus direct primitive parent state. It adds no component rerenderer, VDOM, hydration, or general capture runtime.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.7
+```
+
+## 0.8.6 - Responsive list reversals
+
+Kudzu 0.8.6 fixes stale keyed-list bookkeeping after reverse and one-item removal fast paths.
+
+### Fixed in 0.8.6
+
+- Reverse fast paths now store the latest logical item order after moving existing keyed DOM nodes.
+- One-item removal fast paths update the same baseline before subsequent list actions.
+- Repeated reverse clicks apply on the next microtask instead of requiring another delayed interaction.
+- Existing keyed rows retain DOM identity and uncontrolled input values through every reorder.
+- Chrome coverage verifies `3,2,1 → 1,2,3 → 3,2,1` across rapid actions, and the complete suite passes 134/134 tests.
+
+### Boundary
+
+This is a bookkeeping correction in the existing keyed-list runtime. It adds no list capability, VDOM, hydration, or component runtime.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.6
+```
+
 ## 0.8.5 - Owned timer actions
 
 Kudzu 0.8.5 compiles one proven private timeout ref pattern from a returned relative custom-hook action into existing state and effect ownership.

package/framework/build.mjs

@@ -303,6 +303,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       .replace("function fillListItem(root, item, nested = false, index = 0)", "function fillListItem(root, item, nested = false)")
       .replace("fillListParts(root, parts, item, revision, index, previous)", "fillListParts(root, parts, item, revision, previous)")
       .replace("function fillListParts(root, parts, item, revision, index = 0, previous)", "function fillListParts(root, parts, item, revision, previous)")
+      .replace("fillListExpressions(root, parts, item, revision, index)", "fillListExpressions(root, parts, item, revision)")
       .replaceAll('value?.type === "list-item" ? serializeItem(item) : value?.type === "list-index" ? index : value', 'value?.type === "list-item" ? serializeItem(item) : value')
       .replaceAll("evaluate(descriptor, item, index)", "evaluate(descriptor, item)")
       .replaceAll("evaluate({ module, handler }, item, index)", "evaluate({ module, handler }, item)")
@@ -311,6 +312,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       .replace("fillListParts(marker, listItemParts(fragment), item, revision, index)", "fillListParts(marker, listItemParts(fragment), item, revision)")
       .replace("function evaluate(descriptor, item, index)", "function evaluate(descriptor, item)")
       .replace("exports[descriptor.handler](item, index)", "exports[descriptor.handler](item)")
+      .replace("exports[descriptor.handler](item, index, {", "exports[descriptor.handler](item, undefined, {")
     if (!hasCollectionSelectors) listRuntime = listRuntime.replaceAll(" && !list.descriptor.selector", "")
     if (!hasListIndexes) listRuntime = listRuntime
       .replaceAll(" && !list.descriptor.indexed", "")
@@ -3899,11 +3901,11 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       }
 
       if (ts.isJsxExpression(node) && node.expression && listValues.has(node.expression)) {
-        return factory.updateJsxExpression(node, compileListValue(node.expression, listValues.get(node.expression), factory, listExpressions, handlerUrl))
+        return factory.updateJsxExpression(node, compileListValue(node.expression, listValues.get(node.expression), factory, context, 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)))
+        return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, compileListValue(node.initializer.expression, listValues.get(node.initializer.expression), factory, context, listExpressions, handlerUrl)))
       }
 
       if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
@@ -4509,9 +4511,12 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
         return
       }
       if (referencesIdentifier(expression, item) || parts.index && referencesIdentifier(expression, parts.index)) {
-        validateListExpression(expression, item, node, fail, parts.index)
+        const states = referencedStateNames(expression, setters)
+        for (const rowState of rowStates) states.delete(rowState.state)
+        if (parts.nested && states.size) fail(node, "Nested keyed list item expressions cannot read parent state")
+        validateListExpression(expression, item, node, fail, parts.index, states)
         if (ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.text.toLowerCase())) fail(node, `Keyed list item ${node.parent.name.text} is not supported`)
-        listValues.set(node.expression, { item, index: parts.index })
+        listValues.set(node.expression, { item, index: parts.index, states })
         return
       }
     }
@@ -4983,7 +4988,7 @@ const assignmentOperators = new Set([
   ts.SyntaxKind.QuestionQuestionEqualsToken
 ])
 
-function validateListExpression(expression, item, source, fail, index) {
+function validateListExpression(expression, item, source, fail, index, states = new Set()) {
   const visit = node => {
     if (ts.isTypeNode(node)) return
     if (ts.isElementAccessExpression(node) && referencesIdentifier(node.expression, item)) {
@@ -5014,7 +5019,7 @@ function validateListExpression(expression, item, source, fail, index) {
         fail(source, "Derived keyed list item expressions cannot call arbitrary functions")
       }
     }
-    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isJsxSyntaxIdentifier(node) && node.text !== item && node.text !== index && !pureListGlobals.has(node.text)) {
+    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isJsxSyntaxIdentifier(node) && node.text !== item && node.text !== index && !states.has(node.text) && !pureListGlobals.has(node.text)) {
       fail(source, `Derived keyed list item expression identifier "${node.text}" is not allowed`)
     }
     ts.forEachChild(node, visit)
@@ -5032,10 +5037,12 @@ function containsJsx(root) {
   return found
 }
 
-function compileListExpression(read, expression, item, factory, listExpressions, handlerUrl, index) {
+function compileListExpression(read, expression, item, factory, listExpressions, handlerUrl, index, states = new Set()) {
   const exportName = `listExpression${listExpressions.length}`
-  listExpressions.push({ exportName, expression, item, index })
-  return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)])
+  listExpressions.push({ exportName, expression, item, index, states })
+  const arguments_ = [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)]
+  if (states.size) arguments_.push(factory.createArrayLiteralExpression([...states].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
+  return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, arguments_)
 }
 
 function compileListConditional(entry, factory, listExpressions, handlerUrl) {
@@ -5048,11 +5055,17 @@ function compileListConditional(entry, factory, listExpressions, handlerUrl) {
   ])
 }
 
-function compileListValue(expression, entry, factory, listExpressions, handlerUrl) {
-  const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), expression)
+function compileListValue(expression, entry, factory, context, listExpressions, handlerUrl) {
+  const rewrite = node => {
+    if (ts.isShorthandPropertyAssignment(node) && entry.states?.has(node.name.text)) return factory.createPropertyAssignment(node.name, factory.createPropertyAccessExpression(node.name, "value"))
+    if (ts.isIdentifier(node) && entry.states?.has(node.text) && isReferenceIdentifier(node)) return factory.createPropertyAccessExpression(node, "value")
+    return ts.visitEachChild(node, rewrite, context)
+  }
+  const initial = entry.states?.size ? ts.visitNode(expression, rewrite) : expression
+  const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), initial)
   return entry.field
     ? factory.createCallExpression(factory.createIdentifier("__kListField"), undefined, [read, factory.createStringLiteral(entry.field)])
-    : compileListExpression(read, expression, entry.item, factory, listExpressions, handlerUrl, entry.index)
+    : compileListExpression(read, expression, entry.item, factory, listExpressions, handlerUrl, entry.index, entry.states)
 }
 
 function directProperty(expression, objectName) {
@@ -6307,17 +6320,35 @@ function printReactiveBinding({ exportName, expression, captures, states }) {
   }
 }
 
-function printListExpression({ exportName, expression, item, index }) {
+function printListExpression({ exportName, expression, item, index, states = new Set() }) {
+  const factory = ts.factory
+  const transformer = context => root => {
+    const visitor = node => {
+      if (ts.isShorthandPropertyAssignment(node) && states.has(node.name.text)) {
+        return factory.createPropertyAssignment(node.name, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(node.name.text)]))
+      }
+      if (ts.isIdentifier(node) && states.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression)) {
+        return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(node.text)])
+      }
+      return ts.visitEachChild(node, visitor, context)
+    }
+    return ts.visitNode(root, visitor)
+  }
+  const transformed = ts.transform(expression, [transformer])
   const declaration = ts.factory.createFunctionDeclaration(
     [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
     undefined,
     exportName,
     undefined,
-    [ts.factory.createParameterDeclaration(undefined, undefined, item), ts.factory.createParameterDeclaration(undefined, undefined, index ?? "__kIndex")],
+    [ts.factory.createParameterDeclaration(undefined, undefined, item), ts.factory.createParameterDeclaration(undefined, undefined, index ?? "__kIndex"), ts.factory.createParameterDeclaration(undefined, undefined, "__k")],
     undefined,
-    ts.factory.createBlock([ts.factory.createReturnStatement(expression)], true)
+    ts.factory.createBlock([ts.factory.createReturnStatement(transformed.transformed[0])], true)
   )
-  return ts.createPrinter().printNode(ts.EmitHint.Unspecified, declaration, expression.getSourceFile())
+  try {
+    return ts.createPrinter().printNode(ts.EmitHint.Unspecified, declaration, expression.getSourceFile())
+  } finally {
+    transformed.dispose()
+  }
 }
 
 function scopeRead(factory, name) {

package/framework/core.d.ts

@@ -38,7 +38,7 @@ 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 | null, render: (item: unknown, index: number) => unknown, ownerField?: string, selector?: unknown[], indexed?: boolean, selectorStates?: Array<[string, unknown]>, staticCollection?: boolean): unknown
 export function listField(read: () => unknown, field: string): unknown
-export function listExpression(read: () => unknown, module: string, handler: string): unknown
+export function listExpression(read: () => unknown, module: string, handler: string, states?: Array<[string, unknown]>): unknown
 export function listItem(): unknown
 export function listIndex(): unknown
 export function listConditional(kind: "and" | "ternary", read: () => unknown, truthy: () => unknown, falsy: () => unknown, module: string, handler: string): unknown

package/framework/core.mjs

@@ -324,11 +324,17 @@ export function listField(read, field) {
   return { [listFieldMarker]: true, field, value: renderContext?.listTemplate ? undefined : read() }
 }
 
-export function listExpression(read, module, handler) {
+export function listExpression(read, module, handler, states = []) {
   renderContext?.handlerModules.add(module)
+  const stateMap = Object.fromEntries(states.map(([name, state]) => {
+    if (!state?.[signalMarker] || !validEffectDependency(state.value)) throw new Error(`Derived keyed list item expression state ${JSON.stringify(name)} must be primitive Kudzu state`)
+    return [name, state.id]
+  }))
+  const owner = renderContext?.listRoot ?? renderContext?.listRowRoot
+  if (owner && states.length) owner.descriptor.expressionStates = [...new Set([...(owner.descriptor.expressionStates ?? []), ...Object.values(stateMap)])]
   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 }
+  return { [listExpressionMarker]: true, module, handler, states: stateMap, value }
 }
 
 export function listItem() {
@@ -659,7 +665,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     return `<template${marker}></template>${escapeHtml(node.value ?? "")}<template data-k-list-text-end></template>`
   }
   if (node?.[listExpressionMarker]) {
-    const descriptor = { module: node.module, handler: node.handler }
+    const descriptor = { module: node.module, handler: node.handler, ...(Object.keys(node.states).length ? { states: node.states } : {}) }
     const marker = renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch ? ` data-k-list-expression='${escapeJsonAttribute(descriptor)}'` : ""
     return `<template${marker}></template>${escapeHtml(node.value ?? "")}<template data-k-list-expression-end></template>`
   }
@@ -812,7 +818,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     }
     if (value?.[listExpressionMarker]) {
       attributes += renderAttribute(name, value.value)
-      listExpressionAttributes.push([name, value.module, value.handler])
+      listExpressionAttributes.push([name, value.module, value.handler, ...(Object.keys(value.states).length ? [value.states] : [])])
       if (name === "style") renderContext.hasListStyles = true
       continue
     }

package/framework/list-runtime.js

@@ -25,7 +25,10 @@ function commitLists(id) {
   if (!lists) return
   for (const list of lists) {
     if (!list.start.isConnected) unregisterList(list.start)
-    else updateList(list)
+    else {
+      if (list.updateStates.has(id)) updateList(list)
+      if (list.expressionStates.has(id)) updateListExpressions(list)
+    }
   }
 }
 
@@ -76,6 +79,8 @@ function mountLists(root) {
       ...(__KUDZU_LIST_STABLE_FAST_PATHS__ ? { orderedRoots: roots } : {}),
       values: new Map(),
       items: undefined,
+      updateStates: new Set(),
+      expressionStates: new Set(descriptor.expressionStates ?? []),
       container: roots[0]?.parentNode,
       boundary: end,
       ...(__KUDZU_NESTED_LISTS__ && descriptor.ownerField ? { owner: nested.owner } : {})
@@ -93,20 +98,19 @@ function mountLists(root) {
       loadListEvaluator(descriptor.source).then(evaluator => {
         if (listLoads.get(start) !== load || !start.isConnected) return
         list.sourceEvaluator = evaluator
-        const states = [...new Set([...evaluator.stateIds, ...(__KUDZU_COLLECTION_SELECTORS__ ? Object.values(descriptor.selectorStates ?? {}) : [])])]
+        const updateStates = [...new Set([...evaluator.stateIds, ...(__KUDZU_COLLECTION_SELECTORS__ ? Object.values(descriptor.selectorStates ?? {}) : [])])]
+        const states = [...new Set([...updateStates, ...list.expressionStates])]
+        list.updateStates = new Set(updateStates)
         for (const state of states) register(listTargets, state, list)
         listRegistrations.set(start, { states, list })
         updateList(list)
       }).catch(error => console.error(error))
     } else {
-      if (__KUDZU_COLLECTION_SELECTORS__ && descriptor.selectorStates) {
-        const states = [...new Set([descriptor.state, ...Object.values(descriptor.selectorStates)])]
-        for (const state of states) register(listTargets, state, list)
-        listRegistrations.set(start, { states, list })
-      } else {
-        register(listTargets, descriptor.state, list)
-        listRegistrations.set(start, { state: descriptor.state, list })
-      }
+      const updateStates = [descriptor.state, ...(__KUDZU_COLLECTION_SELECTORS__ ? Object.values(descriptor.selectorStates ?? {}) : [])]
+      const states = [...new Set([...updateStates, ...list.expressionStates])]
+      list.updateStates = new Set(updateStates)
+      for (const state of states) register(listTargets, state, list)
+      listRegistrations.set(start, { states, list })
     }
     if (!descriptor.source) updateList(list)
   }
@@ -125,7 +129,7 @@ function unregisterList(start) {
       if (lists?.get(registration.list.descriptor.id) === registration.list) lists.delete(registration.list.descriptor.id)
       if (!lists?.size) ownedLists.delete(registration.owner)
     } else {
-      if ((__KUDZU_COLLECTION_SELECTORS__ || registration.list.descriptor.source) && registration.states) {
+      if (registration.states) {
         for (const state of registration.states) {
           const lists = listTargets.get(state)
           lists?.delete(registration.list)
@@ -198,6 +202,7 @@ function updateList(list) {
       list.roots = new Map(nextTokens.map(token => [token, list.roots.get(token)]))
       if (__KUDZU_LIST_STABLE_FAST_PATHS__) list.orderedRoots = nextTokens.map(token => list.roots.get(token))
       list.container ??= parent
+      list.items = items
       return
     }
     if (nextTokens.length === currentTokens.length - 1) {
@@ -207,6 +212,7 @@ function updateList(list) {
         removeListRoot(list, removed)
         list.roots = new Map(nextTokens.map(token => [token, list.roots.get(token)]))
         if (__KUDZU_LIST_STABLE_FAST_PATHS__) list.orderedRoots = nextTokens.map(token => list.roots.get(token))
+        list.items = items
         return
       }
     }
@@ -645,6 +651,17 @@ function fillListParts(root, parts, item, revision, index = 0, previous) {
       }
     }
   }
+  fillListExpressions(root, parts, item, revision, index)
+  if (__KUDZU_LIST_CONDITIONS__) {
+    for (const [marker, descriptor] of parts.conditions) {
+      evaluate(descriptor, item, index).then(value => {
+        if (revisions.get(root) === revision && marker.isConnected) updateListCondition(marker, descriptor.kind, value, item, index)
+      }).catch(error => console.error(error))
+    }
+  }
+}
+
+function fillListExpressions(root, parts, item, revision, index) {
   if (__KUDZU_LIST_EXPRESSIONS__) {
     for (const [marker, descriptor] of parts.expressions) {
       evaluate(descriptor, item, index).then(value => {
@@ -654,19 +671,20 @@ function fillListParts(root, parts, item, revision, index = 0, previous) {
   }
   if (__KUDZU_LIST_EXPRESSION_ATTRIBUTES__) {
     for (const [node, attributes] of parts.expressionAttributes) {
-      for (const [target, module, handler] of attributes) {
-        evaluate({ module, handler }, item, index).then(value => {
+      for (const [target, module, handler, states] of attributes) {
+        evaluate({ module, handler, states }, item, index).then(value => {
           if (revisions.get(root) === revision && node.isConnected) patchBinding(node, target, value)
         }).catch(error => console.error(error))
       }
     }
   }
-  if (__KUDZU_LIST_CONDITIONS__) {
-    for (const [marker, descriptor] of parts.conditions) {
-      evaluate(descriptor, item, index).then(value => {
-        if (revisions.get(root) === revision && marker.isConnected) updateListCondition(marker, descriptor.kind, value, item, index)
-      }).catch(error => console.error(error))
-    }
+}
+
+function updateListExpressions(list) {
+  for (const root of list.roots.values()) {
+    const revision = (revisions.get(root) ?? 0) + 1
+    revisions.set(root, revision)
+    fillListExpressions(root, listItemParts(root, list.descriptor.nested), listItems.get(root), revision, __KUDZU_LIST_INDEXES__ ? listIndexes.get(root) ?? 0 : 0)
   }
 }
 
@@ -997,7 +1015,7 @@ function evaluate(descriptor, item, index) {
     imports.set(descriptor.module, module)
   }
   return module.then(exports => {
-    const value = exports[descriptor.handler](item, index)
+    const value = exports[descriptor.handler](item, index, { get: name => browserState.get(descriptor.states?.[name]) })
     if (value && typeof value.then === "function") throw new Error("Derived keyed list item expressions must return synchronous values")
     return value
   })

package/package.json

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