@kudzujs/core 0.6.25 → 0.6.27

package/README.md

@@ -422,7 +422,16 @@ function ItemCard({ item, onSelect }: {
 
 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.6 ms, and parent removal 0.6 ms. Svelte measured 2.2/0.8/5.4/1.1 ms, Vue 4.3/2.3/5.0/2.0 ms, React 8.9/4.2/7.4/4.1 ms, and hand-written Astro/native 0.5/0.3/3.1/0.1 ms. Kudzu shipped 6.6 KB initial JavaScript gzip and complete initial HTML. Sharing inert child-condition branches and descriptors through each live child-list prototype reduced HTML from 676,086 B to 417,086 B and total deploy output from 693,806 B to 435,326 B raw; the sum of gzip-compressed files is 23,473 B. The CSR targets omit initial rows, so their artifact sizes are not architecture-equivalent.
+#### Nested list output
+
+Initial child rows remain complete HTML. Kudzu stores one child row prototype, including inert condition branches and descriptors, and reuses it across parent rows.
+
+- HTML: 676,086 B before sharing, 339,586 B after sharing.
+- Total deploy output: 693,806 B before sharing, 359,035 B after sharing.
+- Compressed-file sum: 24,067 B. Sharing text and attribute patch metadata saves 29,576 B raw over `v0.6.26` while adding 147 B gzip because the removed metadata compressed well.
+- Initial JavaScript: 6.9 KB gzip. Routes without nested lists compile out prototype and marker lookup.
+
+In the matched 100-parent/1,000-child fixture, Kudzu measured 1.4/0.5/5.4/0.7 ms for child update and condition change, child reverse, parent reverse, and parent removal. Hand-written Astro/native measured 0.5/0.3/3.6/0.2 ms, Svelte 2.2/0.9/5.4/0.9 ms, Vue 4.0/2.1/4.6/1.8 ms, and React 8.5/3.9/6.8/3.8 ms. Kudzu and Astro emit initial rows while the CSR targets do not, so 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 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>`.
 

package/framework/core.mjs

@@ -546,7 +546,9 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (node?.[listMarker]) return renderList(node, namespace, selectValue)
   if (node?.[listFieldMarker]) {
     if (renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) renderContext.listFields?.add(node.field)
-    const marker = renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch ? ` data-k-list-text="${escapeAttribute(node.field)}"` : ""
+    const marker = renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch
+      ? sharedInitialListMarker() ? " data-k-list-text" : ` data-k-list-text="${escapeAttribute(node.field)}"`
+      : ""
     return `<template${marker}></template>${escapeHtml(node.value ?? "")}<template data-k-list-text-end></template>`
   }
   if (node?.[listExpressionMarker]) {
@@ -727,12 +729,12 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
 
   if (attributeBindings.length) attributes += ` data-k-bind-attrs='${escapeJsonAttribute(attributeBindings)}'`
-  if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && listAttributes.length) attributes += ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
+  if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && listAttributes.length) attributes += sharedInitialListMarker() ? " data-k-list-attrs" : ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
   if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && listExpressionAttributes.length) attributes += ` data-k-list-expression-attrs='${escapeJsonAttribute(listExpressionAttributes)}'`
   if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && listEvents.length) attributes += ` data-k-list-events='${escapeJsonAttribute(listEvents)}'`
   if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && directListText) {
     renderContext.listFields?.add(directListText.field)
-    attributes += ` data-k-list-text="${escapeAttribute(directListText.field)}"`
+    attributes += sharedInitialListMarker() ? " data-k-list-text" : ` data-k-list-text="${escapeAttribute(directListText.field)}"`
   }
 
   if (tag === "option" && selectValue !== noSelectValue && String(optionValue(props)) === (selectValue == null ? "" : String(selectValue))) attributes += " selected"
@@ -746,6 +748,11 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   return `<${tag}${attributes}>${children}</${tag}>`
 }
 
+function sharedInitialListMarker() {
+  const owner = renderContext.listRoot ?? renderContext.listRowRoot
+  return renderContext.listInitialMarkers && !renderContext.listTemplate && !renderContext.listConditionalBranch && owner?.descriptor.ownerField
+}
+
 async function renderList(node, namespace, selectValue) {
   if (namespace) throw new Error(`Reactive keyed lists are not supported inside ${namespace}`)
   const ownerRoot = node.ownerField ? renderContext.listRoot ?? renderContext.listRowRoot : undefined
@@ -801,7 +808,8 @@ async function renderList(node, namespace, selectValue) {
     if (!node.ownerField || ownerTemplate) renderContext.lists.push(descriptor)
     renderContext.hasBehaviors = true
     renderContext.hasLists = true
-    return `<template data-k-list='${escapeJsonAttribute(descriptor)}'>${template}</template>${current}<template data-k-list-end="${id}"></template>`
+    const prototype = node.ownerField && !ownerTemplate ? "" : template
+    return `<template data-k-list='${escapeJsonAttribute(descriptor)}'>${prototype}</template>${current}<template data-k-list-end="${id}"></template>`
   } finally {
     renderContext.listRoot = previousListRoot
     renderContext.listRowRoot = previousListRowRoot

package/framework/list-runtime.js

@@ -11,6 +11,8 @@ 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]" : ""}`
+const childPrototypes = __KUDZU_NESTED_LISTS__ ? new WeakMap() : undefined
+const itemPartPlans = __KUDZU_NESTED_LISTS__ ? new WeakMap() : undefined
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -37,11 +39,13 @@ function mountLists(root) {
     const descriptor = JSON.parse(start.dataset.kList)
     const end = findEnd(start, descriptor.id)
     const roots = listRoots(start, end)
+    const nested = __KUDZU_NESTED_LISTS__ ? mountNestedPrototype(start, descriptor, roots) : undefined
+    const templateRoot = __KUDZU_NESTED_LISTS__ ? nested.templateRoot : start.content.firstElementChild
     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) {
       if (__KUDZU_LIST_CONDITIONS__ && descriptor.conditions) {
+        if (__KUDZU_NESTED_LISTS__ && descriptor.ownerField) itemPartPlans.set(root, parts)
         const initialParts = listItemParts(root, descriptor.nested)
         mapListConditionTemplates(parts.conditions, initialParts.conditions)
       } else mapListItemParts(parts, root, descriptor.nested)
@@ -51,6 +55,7 @@ function mountLists(root) {
     const list = {
       start,
       descriptor,
+      ...(__KUDZU_NESTED_LISTS__ ? { templateRoot, ...(nested.childPrototype ? { childPrototype: nested.childPrototype } : {}) } : {}),
       parts,
       seedFields: __KUDZU_LIST_SEEDS__ && descriptor.seed && Object.keys(descriptor.seed),
       roots: new Map(roots.map((node, index) => [keyToken(descriptor.keys[index]), node])),
@@ -58,7 +63,7 @@ function mountLists(root) {
       items: undefined,
       container: roots[0]?.parentNode,
       boundary: end,
-      ...(__KUDZU_NESTED_LISTS__ && descriptor.ownerField ? { owner: listOwner(start) } : {})
+      ...(__KUDZU_NESTED_LISTS__ && descriptor.ownerField ? { owner: nested.owner } : {})
     }
     if (__KUDZU_NESTED_LISTS__ && descriptor.ownerField) {
       if (!list.owner) throw new Error("Nested keyed list has no parent row")
@@ -150,10 +155,11 @@ function updateList(list) {
   for (const { item, key, token, value } of entries) {
     let node = list.roots.get(token)
     if (!node) {
-      node = list.start.content.firstElementChild?.cloneNode(true)
+      node = (__KUDZU_NESTED_LISTS__ ? list.templateRoot : list.start.content.firstElementChild)?.cloneNode(true)
       if (node?.dataset.kListRoot !== list.descriptor.id) node = undefined
       if (!node) throw new Error("Keyed list template has no root element")
       node.removeAttribute("data-k-list-root")
+      if (__KUDZU_NESTED_LISTS__ && list.childPrototype) childPrototypes.set(node, list.childPrototype)
       if (__KUDZU_LIST_ROW_STATES__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)
       mapListItemParts(list.parts, node, list.descriptor.nested)
       fillListItem(node, item, list.descriptor.nested)
@@ -323,10 +329,11 @@ function updateReducerList(list, items) {
 }
 
 function addListRoot(list, { item, key, token, value }) {
-  let node = list.start.content.firstElementChild?.cloneNode(true)
+  let node = (__KUDZU_NESTED_LISTS__ ? list.templateRoot : list.start.content.firstElementChild)?.cloneNode(true)
   if (node?.dataset.kListRoot !== list.descriptor.id) node = undefined
   if (!node) throw new Error("Keyed list template has no root element")
   node.removeAttribute("data-k-list-root")
+  if (__KUDZU_NESTED_LISTS__ && list.childPrototype) childPrototypes.set(node, list.childPrototype)
   if (__KUDZU_LIST_ROW_STATES__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)
   mapListItemParts(list.parts, node, list.descriptor.nested)
   fillListItem(node, item, list.descriptor.nested)
@@ -418,7 +425,7 @@ function listItemParts(root, nested = false) {
   parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [], conditions: [], effects: [] }
   for (const node of nested ? ownedElements(root).filter(node => node.matches(itemPartsSelector)) : matching(root, itemPartsSelector)) {
     if (node.hasAttribute("data-k-list-text")) (node.tagName === "TEMPLATE" ? parts.texts : parts.directTexts).push([node, node.dataset.kListText])
-    if (__KUDZU_LIST_ATTRIBUTES__ && node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, JSON.parse(node.dataset.kListAttrs)])
+    if (__KUDZU_LIST_ATTRIBUTES__ && node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, node.dataset.kListAttrs ? JSON.parse(node.dataset.kListAttrs) : undefined])
     if (__KUDZU_LIST_EVENTS__ && node.hasAttribute("data-k-list-events")) parts.events.push([node, node.dataset.kListEvents])
     if (__KUDZU_LIST_EXPRESSIONS__ && node.hasAttribute("data-k-list-expression")) parts.expressions.push([node, JSON.parse(node.dataset.kListExpression)])
     if (__KUDZU_LIST_EXPRESSION_ATTRIBUTES__ && node.hasAttribute("data-k-list-expression-attrs")) parts.expressionAttributes.push([node, JSON.parse(node.dataset.kListExpressionAttrs)])
@@ -429,10 +436,28 @@ function listItemParts(root, nested = false) {
     }
     if (__KUDZU_LIST_EFFECTS__ && node.hasAttribute("data-k-effects")) parts.effects.push(node)
   }
+  if (__KUDZU_NESTED_LISTS__) hydrateListItemParts(itemPartPlans.get(root), parts)
   itemParts.set(root, parts)
   return parts
 }
 
+function hydrateListItemParts(planned, initial) {
+  if (!planned) return
+  hydrateListItemPartValues(planned.directTexts, initial.directTexts, value => value === "")
+  if (__KUDZU_LIST_TEXT_RANGES__) hydrateListItemPartValues(planned.texts, initial.texts, value => value === "")
+  if (__KUDZU_LIST_ATTRIBUTES__) hydrateListItemPartValues(planned.attributes, initial.attributes, value => value === undefined)
+}
+
+function hydrateListItemPartValues(planned, initial, missing) {
+  let index = 0
+  for (const entry of initial) {
+    if (!missing(entry[1])) continue
+    if (!planned[index]) throw new Error("Keyed list item markers do not match its template")
+    entry[1] = planned[index++][1]
+  }
+  if (index !== planned.length) throw new Error("Keyed list item markers do not match its template")
+}
+
 function listItemPartPlan(template, nested = false) {
   const source = nested ? ownedElements(template) : [template, ...template.querySelectorAll("*")]
   const indexes = new Map(source.map((node, index) => [node, index]))
@@ -537,6 +562,31 @@ function listOwner(start) {
   return owner
 }
 
+function mountNestedPrototype(start, descriptor, roots) {
+  const owner = descriptor.ownerField ? listOwner(start) : undefined
+  const prototypeStart = owner ? childPrototypes.get(owner) : undefined
+  const templateRoot = prototypeStart?.content.firstElementChild ?? start.content.firstElementChild
+  if (!templateRoot) throw new Error("Nested keyed list has no shared row prototype")
+  const childPrototype = descriptor.child ? findChildPrototype(templateRoot, descriptor.child.field) : undefined
+  if (descriptor.child && !childPrototype) throw new Error("Keyed list template has no nested row prototype")
+  if (childPrototype) for (const root of roots) childPrototypes.set(root, childPrototype)
+  if (prototypeStart && start !== prototypeStart) start.content.replaceChildren()
+  return { owner, childPrototype, templateRoot }
+}
+
+function findChildPrototype(root, field) {
+  for (const element of root.children) {
+    if (element.matches("template[data-k-list]")) {
+      if (JSON.parse(element.dataset.kList).ownerField === field) return element
+      const nested = findChildPrototype(element.content, field)
+      if (nested) return nested
+    } else {
+      const nested = findChildPrototype(element, field)
+      if (nested) return nested
+    }
+  }
+}
+
 function ownedElements(root) {
   const elements = []
   const visit = node => {

package/package.json

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