@kudzujs/core 0.8.8 → 0.8.10

package/README.md

@@ -8,9 +8,13 @@ HTML-first TSX framework with synchronous state semantics and no virtual DOM.
 
 Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTML, CSS, and only the route-specific ESM capabilities actually used. Static pages ship zero JavaScript. React, hydration, a VDOM, and a retained browser component tree are not part of the output.
 
+[![Watch the 22-second Kudzu compiler overview](https://raw.githubusercontent.com/kudzujs/kudzu/main/media/kudzu-demo-cover.png)](https://github.com/kudzujs/kudzu/blob/main/media/kudzu-demo.mp4)
+
+*Watch: React-shaped TSX to static HTML and route-specific ESM in 22 seconds.*
+
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.8 - Conditional keyed map roots.** Expression-bodied keyed maps may return `condition && <Row />` or `condition ? <Row /> : null`; Kudzu lowers the condition to its existing filter path so omitted rows clean up and re-entry starts fresh. Read the [release notes](./RELEASES.md#088---conditional-keyed-map-roots) or open the [release page](https://kudzujs.cloud/releases/0.8.8).
+**Latest release: 0.8.10 - Native dialog migration.** A reduced shadcn/Radix-shaped dialog now proves how AI migration can preserve `forwardRef`, props, children, refs, and handlers while replacing package-owned Portal and Context behavior with native `<dialog>`. Read the [release notes](./RELEASES.md#0810---native-dialog-migration) or open the [release page](https://kudzujs.cloud/releases/0.8.10).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,57 @@
 # Kudzu Releases
 
+## 0.8.10 - Native dialog migration
+
+Kudzu 0.8.10 proves a source migration path from a shadcn/Radix-shaped dialog to the native `<dialog>` element without adding package compatibility runtime.
+
+### New in 0.8.10
+
+- A reduced migration fixture preserves a relative `forwardRef` component, props, children, object refs, and ordinary JSX event handlers.
+- Package-owned Portal and Context behavior becomes native `showModal()`, `close()`, and cancel handling.
+- Complete accessible dialog markup is pre-rendered while route output includes only the `click` and `cancel` events it uses.
+- Chrome coverage verifies modal top-layer behavior, initial focus, confirm and cancel paths, and explicit trigger-focus restoration.
+- Public documentation now includes the migration recipe and its deliberate library boundary.
+
+### Fixed in 0.8.10
+
+- Mobile documentation code blocks stay within the content grid and scroll horizontally instead of widening the viewport.
+- Browser tests allow slower CI Chrome startup and report process timeouts directly instead of failing later against empty DOM output.
+- The complete suite passes 140/140 tests.
+
+### Boundary
+
+This release does not execute Radix or arbitrary React UI packages. `Portal`, `asChild`/`Slot`, element cloning, and arbitrary compound-component Context must be removed during source migration. Applications remain responsible for dialog labeling and explicit focus restoration.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.10
+```
+
+## 0.8.9 - Context-backed CRUD actions
+
+Kudzu 0.8.9 specializes state-backed actions exposed through one conventional Context Provider and relative custom hook.
+
+### New in 0.8.9
+
+- A relative zero-argument custom hook may directly return `useContext(ContextIdentifier)` from one local or named relative Context module.
+- One Provider may expose direct shorthand `useState` pairs and synchronous actions that capture only those exposed pairs.
+- Consumers may select state and actions across ordinary component boundaries; direct action calls inline into existing route handler ESM and concrete state operations.
+- CRUD actions over object arrays compose with keyed rows, reactive selection, conditional editors, and guarded local storage effects in the React Notes migration.
+- Unsupported private captures, hidden state dependencies, indirect action references, dynamic Provider values, multiple Providers, and consumer binding collisions fail with source diagnostics.
+- Static sibling routes remain JavaScript-free. No action function, Context runtime, Provider tree, callback registry, VDOM, or hydration is emitted.
+- The complete suite passes 139/139 tests, including Chrome coverage for create, rename, select, and delete behavior.
+
+### Boundary
+
+The hook must directly return `useContext(ContextIdentifier)`. The Context and exactly one Provider must be declared together in one local or named relative module, and its value must be one direct shorthand object. Actions must be synchronous, called directly in intrinsic handlers, and capture only exposed Provider state pairs.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.9
+```
+
 ## 0.8.8 - Conditional keyed map roots
 
 Kudzu 0.8.8 compiles ordinary expression-bodied conditional keyed maps through the existing pure collection selector path.

package/framework/build.mjs

@@ -2843,6 +2843,78 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     let usesComponentRef = false
     let usesComponentEffects = false
 
+    const resolveContextHook = (returned, hookSource) => {
+      if (!hasFrameworkImport(hookSource, "useContext")) throw sourceNodeError(returned.expression, hookSource, "Relative Context hooks must call useContext imported from react or @kudzujs/core")
+      if (returned.arguments.length !== 1 || !ts.isIdentifier(returned.arguments[0])) throw sourceNodeError(returned, hookSource, "Relative Context hooks must directly return useContext(ContextIdentifier)")
+      const contextName = returned.arguments[0].text
+      let providerSource = hookSource
+      let providerContextName = contextName
+      const hookImports = clientImportBindings(hookSource, hookSource.fileName, sourceFiles)
+      if (hookImports.has(contextName)) {
+        const binding = hookImports.get(contextName)
+        if (binding.kind === "namespace" || binding.kind === "default") throw sourceNodeError(returned.arguments[0], hookSource, "Relative Context hooks require a named Context import")
+        providerSource = importedSource(binding.target)
+        providerContextName = binding.imported
+      }
+      const hasContext = hasFrameworkImport(providerSource, "createContext") && providerSource.statements.some(statement => ts.isVariableStatement(statement) && statement.declarationList.declarations.some(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === providerContextName && declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "createContext"))
+      if (!hasContext) throw sourceNodeError(returned.arguments[0], hookSource, "Relative Context hooks require a local or named relative createContext() declaration")
+
+      const providers = []
+      const findProviders = node => {
+        if (ts.isJsxAttribute(node) && node.name.text === "value") {
+          const element = node.parent?.parent
+          const tag = ts.isJsxOpeningElement(element) || ts.isJsxSelfClosingElement(element) ? element.tagName : undefined
+          if (ts.isPropertyAccessExpression(tag) && tag.name.text === "Provider" && ts.isIdentifier(tag.expression) && tag.expression.text === providerContextName) providers.push(node)
+        }
+        ts.forEachChild(node, findProviders)
+      }
+      findProviders(providerSource)
+      if (providers.length !== 1) throw sourceNodeError(returned.arguments[0], hookSource, "Relative Context hooks require exactly one Provider value in the Context module")
+      const provider = providers[0]
+      const value = provider.initializer && ts.isJsxExpression(provider.initializer) && provider.initializer.expression ? unwrapExpression(provider.initializer.expression) : undefined
+      if (!value || !ts.isObjectLiteralExpression(value)) throw sourceNodeError(provider, providerSource, "Context Provider value must be one direct object literal")
+      const owner = nearestFunction(provider)
+      if (!owner) throw sourceNodeError(provider, providerSource, "Context Provider value must be returned by a component")
+
+      const states = new Map()
+      const callbacks = new Map()
+      const hasUseState = hasFrameworkImport(providerSource, "useState")
+      const collectProviderBindings = node => {
+        if (ts.isVariableDeclaration(node) && nearestFunction(node) === owner) {
+          if (hasUseState && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression) && node.initializer.expression.text === "useState") {
+            const [state, setter] = node.name.elements
+            if (node.name.elements.length === 2 && state && setter && ts.isBindingElement(state) && ts.isBindingElement(setter) && ts.isIdentifier(state.name) && ts.isIdentifier(setter.name)) states.set(setter.name.text, state.name.text)
+          }
+          if (ts.isIdentifier(node.name) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) callbacks.set(node.name.text, node.initializer)
+        }
+        ts.forEachChild(node, collectProviderBindings)
+      }
+      collectProviderBindings(owner.body)
+
+      const fields = new Set()
+      const stateFields = new Set([...states].flat())
+      for (const property of value.properties) {
+        if (!ts.isShorthandPropertyAssignment(property)) throw sourceNodeError(property, providerSource, "Context Provider values must use direct shorthand state, setter, or action fields")
+        const name = property.name.text
+        if (!stateFields.has(name) && !callbacks.has(name)) throw sourceNodeError(property, providerSource, `Context Provider field ${JSON.stringify(name)} must be a direct provider-owned state, setter, or action`)
+        fields.add(name)
+      }
+      for (const [setter, state] of states) {
+        if (fields.has(setter) !== fields.has(state)) throw sourceNodeError(value, providerSource, `Context Provider state ${JSON.stringify(state)} and setter ${JSON.stringify(setter)} must be exposed together`)
+      }
+      for (const [name, callback] of callbacks) {
+        if (!fields.has(name)) continue
+        if (callback.asteriskToken || callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) throw sourceNodeError(callback, providerSource, `Context action ${JSON.stringify(name)} must be synchronous`)
+        const capture = nativeCaptureNames(callback, states).values().next().value
+        if (capture) throw sourceNodeError(callback, providerSource, `Context action ${JSON.stringify(name)} cannot capture private binding ${JSON.stringify(capture)}`)
+        for (const state of referencedStateNames(callback.body, states, callback)) {
+          const setter = [...states].find(([, candidate]) => candidate === state)?.[0]
+          if (!setter || !fields.has(state) || !fields.has(setter)) throw sourceNodeError(callback, providerSource, `Context action ${JSON.stringify(name)} requires exposed state and setter fields for ${JSON.stringify(state)}`)
+        }
+      }
+      return { callbacks: new Map([...callbacks].filter(([name]) => fields.has(name))), context: true, fields, privateStates: new Set(), states }
+    }
+
     const resolveCustomHook = (binding, call) => {
       const exportName = binding.kind === "default" ? "default" : binding.imported
       const key = `${binding.target}:${exportName}`
@@ -2852,7 +2924,12 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       if (hook.parameters.length || hook.asteriskToken || hook.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || !ts.isBlock(hook.body)) throw sourceNodeError(hook, hookSource, "Relative custom hooks must be synchronous zero-argument functions with a block body")
       const returns = hook.body.statements.filter(ts.isReturnStatement)
       const returned = returns.length === 1 && returns[0] === hook.body.statements.at(-1) && returns[0].expression ? unwrapExpression(returns[0].expression) : undefined
-      if (!returned || !ts.isObjectLiteralExpression(returned)) throw sourceNodeError(hook.body, hookSource, "Relative custom hooks must end with one direct object return")
+      if (returned && ts.isCallExpression(returned) && ts.isIdentifier(returned.expression) && returned.expression.text === "useContext") {
+        const analysis = resolveContextHook(returned, hookSource)
+        customHooks.set(key, analysis)
+        return analysis
+      }
+      if (!returned || !ts.isObjectLiteralExpression(returned)) throw sourceNodeError(hook.body, hookSource, "Relative custom hooks must end with one direct object return or direct useContext(ContextIdentifier)")
 
       const states = new Map()
       const callbacks = new Map()
@@ -2897,7 +2974,30 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
           const owner = nearestFunction(node)
           if (!owner) throw sourceNodeError(node, sourceFile, "Relative custom hooks cannot be used outside a Kudzu component")
           const setters = settersByFunction.get(owner) ?? new Map()
+          const requiredContextStates = new Set()
+          if (hook.context) {
+            for (const name of names) {
+              const callback = hook.callbacks.get(name)
+              if (callback) for (const state of referencedStateNames(callback.body, hook.states, callback)) requiredContextStates.add(state)
+            }
+          }
           for (const [setter, state] of hook.states) {
+            if (hook.context) {
+              if (names.has(setter) && !names.has(state)) throw sourceNodeError(node.name, sourceFile, `Relative Context setter ${JSON.stringify(setter)} requires state ${JSON.stringify(state)} to be destructured`)
+              if (!names.has(state) && !requiredContextStates.has(state)) continue
+              setters.set(names.has(setter) || requiredContextStates.has(state) ? setter : `__kContextState_${state}`, state)
+              if (requiredContextStates.has(state)) {
+                const fields = customHookPrivateFields.get(node) ?? []
+                for (const field of [state, setter]) {
+                  if (names.has(field) || fields.includes(field)) continue
+                  const conflict = owner.parameters.some(parameter => bindingNames(parameter.name).includes(field)) || owner.body.statements.some(statement => statement !== node.parent.parent && statementDeclaresName(statement, field))
+                  if (conflict) throw sourceNodeError(node.name, sourceFile, `Context action state field ${JSON.stringify(field)} conflicts with a consumer binding`)
+                  fields.push(field)
+                }
+                customHookPrivateFields.set(node, fields)
+              }
+              continue
+            }
             if (hook.privateStates.has(state)) {
               setters.set(setter, state)
               const fields = customHookPrivateFields.get(node) ?? []
@@ -2914,6 +3014,11 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
               const callbacks = customHookFunctionsByOwner.get(owner) ?? new Map()
               callbacks.set(name, hook.callbacks.get(name))
               customHookFunctionsByOwner.set(owner, callbacks)
+              if (hook.context) {
+                const reducers = reducersByFunction.get(owner) ?? new Map()
+                reducers.set(name, { contextAction: hook.callbacks.get(name), states: hook.states })
+                reducersByFunction.set(owner, reducers)
+              }
             }
             else if (![...hook.states].some(([setter, state]) => name === setter || name === state)) throw sourceNodeError(node.name, sourceFile, `Relative custom hook result ${JSON.stringify(name)} must be a direct useState value, setter, or callback`)
           }
@@ -5251,9 +5356,13 @@ function compileNativeCallback(expression, setters, reducers, factory, entries,
   const usedReducers = referencedReducerDispatches(expression.body, reducers, expression)
   const imports = [...referencedImportedBindings(expression, importBindings)].map(name => importBindings.get(name))
   imports.push(...[...usedReducers].map(name => reducers.get(name).import).filter(Boolean))
-  const captures = new Set([...allCaptures].filter(name => !importBindings.has(name)))
+  const captures = new Set([...allCaptures].filter(name => !importBindings.has(name) && !usedReducers.has(name)))
   for (const entry of imports) if (!entry.package) clientImports.add(entry.target)
   const usedStates = nativeStateNames(expression, setters)
+  for (const name of usedReducers) {
+    const reducer = reducers.get(name)
+    if (reducer.contextAction) for (const state of referencedStateNames(reducer.contextAction.body, reducer.states, reducer.contextAction)) usedStates.add(state)
+  }
   const exportName = `${prefix}${entries.length}`
   entries.push({ exportName, expression, captures, imports, liveStates, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested })
   const value = name => deferValues
@@ -5572,6 +5681,14 @@ function clientImportBindings(sourceFile, file, sourceFiles) {
   return bindings
 }
 
+function hasFrameworkImport(sourceFile, name) {
+  return sourceFile.statements.some(node => {
+    if (!ts.isImportDeclaration(node) || node.importClause?.isTypeOnly || !ts.isStringLiteral(node.moduleSpecifier) || !["react", "@kudzujs/core"].includes(node.moduleSpecifier.text)) return false
+    const bindings = node.importClause?.namedBindings
+    return bindings && ts.isNamedImports(bindings) && bindings.elements.some(entry => !entry.isTypeOnly && entry.name.text === name && (entry.propertyName ?? entry.name).text === name)
+  })
+}
+
 function packageImportBindings(sourceFile) {
   const bindings = new Map()
   const rejectDynamic = node => {
@@ -6136,15 +6253,23 @@ function printNativeHandler({ exportName, expression, captures, setters, reducer
     const visitor = node => {
       if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && reducers.has(node.expression.text) && !isShadowedIdentifier(node.expression, expression)) {
         const reducer = reducers.get(node.expression.text)
+        if (reducer.contextAction) {
+          const action = synthesizeTree(cloneAst(reducer.contextAction, factory, context))
+          const call = factory.createCallExpression(action, undefined, node.arguments)
+          ts.setParentRecursive(call, false)
+          return ts.visitNode(call, visitor)
+        }
         if (reducer.store) return zustandActionDispatch(factory, reducer, node.arguments.map(argument => ts.visitNode(argument, visitor)))
         if (node.arguments.length !== 1) throw sourceNodeError(node, expression.getSourceFile(), "Reducer dispatches require exactly one action")
         return reducerDispatch(factory, reducer, ts.visitNode(node.arguments[0], visitor))
       }
       if (ts.isShorthandPropertyAssignment(node) && reducers.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
+        if (reducers.get(node.name.text).contextAction) throw sourceNodeError(node, expression.getSourceFile(), "Context actions must be called directly inside an event handler")
         if (reducers.get(node.name.text).store) throw sourceNodeError(node, expression.getSourceFile(), "Zustand actions must be called directly inside an event handler")
         return factory.createPropertyAssignment(node.name, reducerReference(factory, reducers.get(node.name.text)))
       }
       if (ts.isIdentifier(node) && reducers.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
+        if (reducers.get(node.text).contextAction) throw sourceNodeError(node, expression.getSourceFile(), "Context actions must be called directly inside an event handler")
         if (reducers.get(node.text).store) throw sourceNodeError(node, expression.getSourceFile(), "Zustand actions must be called directly inside an event handler")
         return reducerReference(factory, reducers.get(node.text))
       }

package/package.json

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