@kudzujs/core 0.6.22 → 0.6.24

package/README.md

@@ -399,15 +399,32 @@ The original row component remains reusable across multiple lists and ordinary J
 One nested keyed map may read a direct array property of its parent item. This supports category/item data populated after mount while preserving both parent and child DOM identity across updates and reorder:
 
 ```tsx
+function ItemCard({ item, onSelect }: {
+  item: Item
+  onSelect: () => void
+}) {
+  return <li>
+    <span>{item.title}</span>
+    {item.available ? <strong>Available</strong> : <small>Unavailable</small>}
+    <button onClick={() => onSelect()}>Select</button>
+  </li>
+}
+
 {categories.map(category => <section key={category.id}>
   <h2>{category.title}</h2>
-  <ul>{category.items.map(item => <li key={item.id}>{item.title}</li>)}</ul>
+  <ul>{category.items.map(item => <ItemCard
+    key={item.id}
+    item={item}
+    onSelect={() => setSelected(item)}
+  />)}</ul>
 </section>)}
 ```
 
-The nested collection must be `parent.<field>`, the child row must have one intrinsic root, and child handlers may capture the child item. A second child list, third nesting level, computed collection, parent-item capture from the child row, child conditions, child effects, child components, and child row-local state remain unsupported.
+The nested collection must be `parent.<field>`. Its child row may be intrinsic or a same-file or relative-imported component that specializes to one intrinsic root. Child handlers receive the latest child item, and one level of child-local `&&` or ternary JSX conditions patches bounded DOM without remounting the child row. A second child list, third nesting level, computed collection, parent-item capture from the child row, conditions inside child conditions, child effects, child component tags below the specialized row root, and child row-local state remain unsupported.
+
+In the matched 100-parent/1,000-child component benchmark, a selected child text and condition update measured 1.2 ms, child reverse 0.4 ms, parent reverse 4.5 ms, and parent removal 0.6 ms. Svelte measured 2.2/0.8/5.2/1.1 ms, Vue 4.2/2.3/5.1/2.1 ms, React 9.2/4.3/7.5/3.8 ms, and hand-written Astro/native 0.4/0.2/3.2/0.2 ms. Kudzu shipped 6.6 KB initial JavaScript gzip and complete initial HTML. Sharing inert child-condition branches through each live child-list prototype reduced HTML from 676,086 B to 509,086 B and total deploy output from 693,806 B to 527,256 B raw; the sum of gzip-compressed files is 24,476 B. The CSR targets omit initial rows, so their artifact sizes are not architecture-equivalent.
 
-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 local-state `.map`, one identifier callback parameter, one intrinsic JSX root or top-level local or relative-imported row component, and `key={item.<field>}`. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Same-file wrappers must be unexported and state-backed at every call; relative default, named/aliased, and direct named re-export wrappers are specialized per qualifying call. Row components accept destructured projected props, top-level single-`const` calculations and inline effects before one intrinsic return. Effect dependencies inside a row may be empty, direct primitive Kudzu state identifiers, or direct `item.<field>` properties whose selected values remain JSON-safe primitives. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` dependencies are rejected. A list alias may only be rendered once and cannot be read by other JavaScript. 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, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package, namespace, and star-export list wrappers, package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, nested item conditions beyond the direct one-level form above, component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. 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 local-state `.map`, one identifier callback parameter, one intrinsic JSX root or top-level local or relative-imported row component, and `key={item.<field>}`. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Same-file wrappers must be unexported and state-backed at every call; relative default, named/aliased, and direct named re-export wrappers are specialized per qualifying call. Row components accept destructured projected props, top-level single-`const` calculations and inline effects before one intrinsic return. Effect dependencies inside a direct outer row may be empty, direct primitive Kudzu state identifiers, or direct `item.<field>` properties whose selected values remain JSON-safe primitives. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` dependencies are rejected. A list alias may only be rendered once and cannot be read by other JavaScript. 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, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package, namespace, and star-export list wrappers, package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, conditions nested inside item conditions, component tags below a specialized row root, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 The focused wrapper fixture emits 1,393 B raw / 500 B gzip HTML and 10,719 B raw / 4,665 B gzip JavaScript across its route capabilities. After one warm-up, seven clean builds measured 314.1, 325.3, 322.3, 327.2, 336.1, 322.4, and 315.0 ms, with a 322.4 ms median.
 

package/framework/build.mjs

@@ -1974,10 +1974,25 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       ts.forEachChild(node, rejectUnsupportedRenderControl)
     }
     rejectUnsupportedRenderControl(sourceFile)
-    const listComponentNames = new Set(rawRenderedLists.flatMap(({ parts }) => {
+    const nestedComponentCalls = new Set()
+    for (const { parts } of rawRenderedLists) {
+      const collectNestedComponents = node => {
+        if (ts.isJsxExpression(node) && node.expression) {
+          const nested = nestedKeyedListParts(node.expression, parts.item)
+          if (nested) {
+            const tag = jsxTagName(nested.root)
+            if (tag && ts.isIdentifier(tag) && tag.text[0] === tag.text[0].toUpperCase()) nestedComponentCalls.add(nested.root)
+            return
+          }
+        }
+        ts.forEachChild(node, collectNestedComponents)
+      }
+      collectNestedComponents(parts.root)
+    }
+    const listComponentNames = new Set([...rawRenderedLists.flatMap(({ parts }) => {
       const tag = jsxTagName(parts.root)
       return tag && ts.isIdentifier(tag) && tag.text[0] === tag.text[0].toUpperCase() ? [tag.text] : []
-    }))
+    }), ...[...nestedComponentCalls].map(call => jsxTagName(call).text)])
     const keyedComponentCalls = new Set(rawRenderedLists.map(({ parts }) => parts.root))
     for (const call of reducerRowStateCalls) if (!keyedComponentCalls.has(call)) fail(call, "Reducer-dispatch component useState() is only supported in a direct keyed row")
     for (const name of listComponentNames) {
@@ -2001,6 +2016,10 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
           ? componentSpecializations.get(call)
           : specializeComponentCall(call, component.function, sourceFile, factory, context, fail)
         if (specialization.effects.length && !keyedComponentCalls.has(call)) fail(call, "Effectful keyed row components may only be used directly as keyed map rows")
+        if (!local) {
+          specialization.root = mergeSpecializedImports(specialization.root, component.function.getSourceFile(), call)
+          synthesizeTree(specialization.root)
+        }
         componentSpecializations.set(call, specialization)
       }
       if (local) specializedDeclarations.add(component.declaration)
@@ -2038,7 +2057,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         calculation.parent = callback
         validateListExpression(calculation, parts.item, originalParts.root, fail)
       }
-      validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, settersForNode(originalParts.root, settersByFunction), specialization?.rowState, nestedLists)
+      validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, settersForNode(originalParts.root, settersByFunction), specialization?.rowState, nestedLists, componentSpecializations, factory)
       if (specialization?.effects.length) {
         usesListEffects = true
         const statements = specialization.effects.map(entry => {
@@ -2520,7 +2539,7 @@ function insideJsxEventHandler(node, root) {
   return false
 }
 
-function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, setters, rowState, nestedLists) {
+function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, setters, rowState, nestedLists, componentSpecializations, factory) {
   const fail = (node, message) => {
     throw sourceNodeError(node, sourceFile, message)
   }
@@ -2550,14 +2569,33 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
         if (nestedList) fail(expression, "Keyed list rows support one nested keyed list")
         if (referenceIdentifiers(nested.callback, item).length) fail(nested.root, "Nested keyed list rows cannot capture the parent item")
         nestedList = nested
-        const nestedParts = { ...nested, state: parts.state, nested: true }
+        const specialization = componentSpecializations.get(nested.root)
+        const root = specialization?.root ?? nested.root
+        const callback = root === nested.root ? nested.callback : factory.updateArrowFunction(
+          nested.callback,
+          nested.callback.modifiers,
+          nested.callback.typeParameters,
+          nested.callback.parameters,
+          nested.callback.type,
+          nested.callback.equalsGreaterThanToken,
+          root
+        )
+        if (callback !== nested.callback) {
+          ts.setParentRecursive(callback, false)
+          callback.parent = nested.callback.parent
+        }
+        const nestedParts = { ...nested, root, callback, state: parts.state, nested: true }
+        for (const calculation of specialization?.calculations ?? []) {
+          ts.setParentRecursive(calculation, false)
+          calculation.parent = callback
+          validateListExpression(calculation, nested.item, nested.root, fail)
+        }
         nestedLists.set(expression, nestedParts)
-        validateKeyedList(nestedParts, sourceFile, listValues, listEventItems, listConditions, setters, undefined, nestedLists)
+        validateKeyedList(nestedParts, sourceFile, listValues, listEventItems, listConditions, setters, undefined, nestedLists, componentSpecializations, factory)
         return
       }
       const condition = conditionalParts(expression)
       if (condition && containsJsx(expression)) {
-        if (parts.nested) fail(node, "Nested keyed list item conditions are not supported")
         if (conditionDepth) fail(node, "Nested item conditions are not supported in keyed lists")
         if (rowState && referencedStateNames(condition.condition, setters).has(rowState.state)) {
           conditionDepth++

package/framework/core.mjs

@@ -568,6 +568,8 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
   if (node?.[listConditionalMarker]) {
     const descriptor = { kind: node.kind, module: node.module, handler: node.handler }
+    const owner = renderContext.listRoot ?? renderContext.listRowRoot
+    if (owner) owner.conditions = true
     const previousBranch = renderContext.listConditionalBranch
     renderContext.listConditionalBranch = true
     let truthy
@@ -583,7 +585,10 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
       ? ""
       : node.kind === "and" && !node.value ? escapeHtml(renderFalsy(node.value)) : node.value ? truthy : falsy
     const initial = renderContext.listTemplate ? "" : ` data-k-list-current="${escapeAttribute(key)}"`
-    return `<template data-k-list-condition='${escapeJsonAttribute(descriptor)}'${initial}><template data-k-list-true>${truthy}</template><template data-k-list-false>${falsy}</template></template>${current}<template data-k-list-condition-end></template>`
+    const branches = renderContext.listInitialMarkers && !renderContext.listTemplate && owner?.descriptor.ownerField
+      ? ""
+      : `<template data-k-list-true>${truthy}</template><template data-k-list-false>${falsy}</template>`
+    return `<template data-k-list-condition='${escapeJsonAttribute(descriptor)}'${initial}>${branches}</template>${current}<template data-k-list-condition-end></template>`
   }
   if (!node || typeof node !== "object" || !("type" in node)) {
     throw new Error(`Cannot render ${String(node)}`)
@@ -765,13 +770,14 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listRowConditions = []
     renderContext.listRowLists = []
     renderContext.listFields = new Set([node.keyField])
-    renderContext.listRoot = { id, state: node.items.id, descriptor, template: true, effects: [], item: {}, rowIndexes: { s: 0, c: 0, l: 0 } }
-    renderContext.listRowRoot = renderContext.listRoot
+    const templateRoot = { id, state: node.items.id, descriptor, template: true, effects: [], item: {}, rowIndexes: { s: 0, c: 0, l: 0 } }
+    renderContext.listRoot = templateRoot
+    renderContext.listRowRoot = templateRoot
     const template = await renderNode(node.render({}), namespace, selectValue)
     if (template.includes("data-k-native-") || template.includes("data-k-effects=") || template.includes("data-k-list=")) descriptor.mount = true
     if (template.includes("data-k-list=")) descriptor.nested = true
     if (template.includes("data-k-effects=")) descriptor.effects = true
-    if (template.includes("data-k-list-condition")) descriptor.conditions = true
+    if (templateRoot.conditions) descriptor.conditions = true
     if (template.includes("data-k-list-text-end")) descriptor.textRanges = true
     if (template.includes("data-k-list-attrs")) descriptor.attributes = true
     if (template.includes("data-k-list-events")) descriptor.events = true

package/framework/list-runtime.js

@@ -9,6 +9,7 @@ const itemParts = new WeakMap()
 const listItems = new WeakMap()
 const ownedLists = __KUDZU_NESTED_LISTS__ ? new WeakMap() : undefined
 const conditionOwners = __KUDZU_LIST_CONDITIONS__ ? new WeakMap() : undefined
+const conditionTemplates = __KUDZU_LIST_CONDITIONS__ ? new WeakMap() : undefined
 const itemPartsSelector = `[data-k-list-text]${__KUDZU_LIST_ATTRIBUTES__ ? ",[data-k-list-attrs]" : ""}${__KUDZU_LIST_EVENTS__ ? ",[data-k-list-events]" : ""}${__KUDZU_LIST_EXPRESSIONS__ ? ",[data-k-list-expression]" : ""}${__KUDZU_LIST_EXPRESSION_ATTRIBUTES__ ? ",[data-k-list-expression-attrs]" : ""}${__KUDZU_LIST_CONDITIONS__ ? ",[data-k-list-condition]" : ""}${__KUDZU_LIST_EFFECTS__ ? ",[data-k-effects]" : ""}`
 
 function commitLists(id) {
@@ -39,7 +40,12 @@ function mountLists(root) {
     if (__KUDZU_LIST_ROW_STATES__ && descriptor.rowStates) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index])
     const templateRoot = start.content.firstElementChild
     const parts = listItemPartPlan(templateRoot, descriptor.nested)
-    for (const root of roots) __KUDZU_LIST_CONDITIONS__ && descriptor.conditions ? listItemParts(root, descriptor.nested) : mapListItemParts(parts, root, descriptor.nested)
+    for (const root of roots) {
+      if (__KUDZU_LIST_CONDITIONS__ && descriptor.conditions) {
+        const initialParts = listItemParts(root, descriptor.nested)
+        mapListConditionTemplates(parts.conditions, initialParts.conditions)
+      } else mapListItemParts(parts, root, descriptor.nested)
+    }
     if (__KUDZU_LIST_SEEDS__ && descriptor.seed && !browserState.has(descriptor.state)) browserState.set(descriptor.state, roots.map((root, index) => seedListItem(root, descriptor, index)))
     const items = browserState.get(descriptor.state)
     const list = {
@@ -429,7 +435,7 @@ function listItemParts(root, nested = false) {
 function listItemPartPlan(template, nested = false) {
   const source = nested ? ownedElements(template) : [template, ...template.querySelectorAll("*")]
   const indexes = new Map(source.map((node, index) => [node, index]))
-  const parts = listItemParts(template)
+  const parts = listItemParts(template, nested)
   return {
     directTexts: parts.directTexts.map(([node, field]) => [indexes.get(node), field]),
     texts: __KUDZU_LIST_TEXT_RANGES__ ? parts.texts.map(([node, field]) => [indexes.get(node), field]) : [],
@@ -437,7 +443,7 @@ function listItemPartPlan(template, nested = false) {
     events: __KUDZU_LIST_EVENTS__ ? parts.events.map(([node, events]) => [indexes.get(node), events]) : [],
     expressions: __KUDZU_LIST_EXPRESSIONS__ ? parts.expressions.map(([node, descriptor]) => [indexes.get(node), descriptor]) : [],
     expressionAttributes: __KUDZU_LIST_EXPRESSION_ATTRIBUTES__ ? parts.expressionAttributes.map(([node, attributes]) => [indexes.get(node), attributes]) : [],
-    conditions: __KUDZU_LIST_CONDITIONS__ ? parts.conditions.map(([node, descriptor]) => [indexes.get(node), descriptor]) : [],
+    conditions: __KUDZU_LIST_CONDITIONS__ ? parts.conditions.map(([node, descriptor]) => [indexes.get(node), descriptor, node]) : [],
     effects: __KUDZU_LIST_EFFECTS__ ? parts.effects.map(node => indexes.get(node)) : []
   }
 }
@@ -459,6 +465,14 @@ function mapListItemParts(parts, root, nested = false) {
   })
 }
 
+function mapListConditionTemplates(planned, initial) {
+  if (planned.length !== initial.length) throw new Error("Keyed list condition markers do not match its template")
+  for (let index = 0; index < initial.length; index++) {
+    const marker = initial[index][0]
+    if (!marker.content.querySelector("template[data-k-list-true],template[data-k-list-false]")) conditionTemplates.set(marker, planned[index][2])
+  }
+}
+
 function updateListCondition(marker, kind, value, item) {
   const current = listConditionKey(kind, value)
   if (marker.dataset.kListCurrent === current) return
@@ -472,9 +486,12 @@ function updateListCondition(marker, kind, value, item) {
     node = next
   }
   const falseText = kind === "and" && !value ? renderFalsy(value) : ""
+  const selector = value ? "template[data-k-list-true]" : "template[data-k-list-false]"
+  const branch = marker.content.querySelector(selector) ?? conditionTemplates.get(marker)?.content.querySelector(selector)
+  if (!falseText && !branch) throw new Error("Keyed list condition marker has no branch template")
   const fragment = falseText
     ? marker.ownerDocument.createDocumentFragment()
-    : marker.content.querySelector(value ? "template[data-k-list-true]" : "template[data-k-list-false]").content.cloneNode(true)
+    : branch.content.cloneNode(true)
   if (falseText) fragment.append(marker.ownerDocument.createTextNode(falseText))
   const nodes = [...fragment.childNodes]
   const revision = (revisions.get(marker) ?? 0) + 1

package/package.json

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