@kudzujs/core 0.7.3 → 0.7.5

package/README.md

@@ -10,7 +10,7 @@ Kudzu is designed so ordinary common React-shaped TSX can migrate with minimal s
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**0.7.3:** React memo normalization. Same-file `memo`, inline `useCallback`, and direct-state expression `useMemo` now compile to existing Kudzu capabilities without React, a VDOM, or hydration. See [release notes](./RELEASES.md#073---react-memo-normalization).
+**0.7.5:** Class composition migration. Direct `clsx` calls compile to ordinary reactive class expressions without shipping the package, and mixed React type imports erase cleanly. See [release notes](./RELEASES.md#075---class-composition-migration).
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
@@ -74,7 +74,9 @@ export default function Header() {
 }
 ```
 
-Kudzu rewrites supported React imports to its compile-time APIs before evaluating the module; neither the React package nor a compatibility runtime enters the deploy output. Named or aliased `useState`, `useReducer`, `useEffect`, `useRef`, `createContext`, and `useContext` imports compile to their canonical forms. Default and namespace imports may call those APIs as direct members such as `React.useState`, and default, namespace, or named `Fragment` also works. `memo(Component)` is erased to a same-file component. Inline `useCallback(function, literalDependencies)` is erased to its function, while inline synchronous `useMemo` callbacks returning one expression over primitive literals and direct local state are inlined at same-component uses so existing bindings track that state. Both hooks require inert literal dependency arrays and complete captured-state dependencies; memo locals cannot be duplicated or captured by nested functions. React classes and side-effect or dynamic React imports remain unsupported. A static route using these forms still emits zero JavaScript.
+Kudzu rewrites supported React imports to its compile-time APIs before evaluating the module; neither the React package nor a compatibility runtime enters the deploy output. Named or aliased `useState`, `useReducer`, `useEffect`, `useRef`, `createContext`, and `useContext` imports compile to their canonical forms. Default and namespace imports may call those APIs as direct members such as `React.useState`, and default, namespace, or named `Fragment` also works. `memo(Component)` is erased to a same-file component. Inline `useCallback(function, literalDependencies)` is erased to its function, while inline synchronous `useMemo` callbacks may return one expression over primitive literals/direct local state or an analyzable `filter`, `map`, `flatMap`, and `Array.from` collection pipeline. Scalar expressions inline into existing bindings; collection pipelines lower to existing keyed-list selectors and preserve row identity. Both hooks require inert literal dependency arrays and complete captured-state dependencies; memo locals cannot be duplicated or captured by nested functions. React classes and side-effect or dynamic React imports remain unsupported. A static route using these forms still emits zero JavaScript.
+
+Direct default or named `clsx` imports compile away for string/number literals, literal arrays, literal object conditions, and conditional expressions. Kudzu lowers those calls to ordinary class expressions, so reactive classes reuse existing bindings without shipping `clsx`; spreads, computed object keys, arbitrary calls, and indirect references remain unsupported.
 
 Create `src/pages/index.tsx`:
 

package/RELEASES.md

@@ -1,5 +1,51 @@
 # Kudzu Releases
 
+## 0.7.5 - Class composition migration
+
+Kudzu 0.7.5 lets ordinary React source retain common direct `clsx` calls while compiling them to existing static and reactive class paths.
+
+### New in 0.7.5
+
+- Default and named `clsx` imports lower at build time for string and number literals, literal arrays, literal object conditions, and conditional expressions.
+- Dynamic object conditions reuse existing reactive class bindings without serializing or shipping the `clsx` function.
+- Static uses add no browser JavaScript, and the package import is erased from compiled modules.
+- Mixed React imports such as `import { useState, type ReactNode } from "react"` now erase type-only specifiers before runtime module rewriting.
+- The React/Vite fixture verifies initial class output, state-driven class updates in Chrome, package erasure, and mixed type imports.
+
+### Boundary
+
+`clsx` spreads, computed object keys, arbitrary calls, and indirect references remain unsupported. This is source lowering for a proven migration pattern, not package execution or a general React ecosystem runtime.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.5
+```
+
+## 0.7.4 - Memoized collection pipelines
+
+Kudzu 0.7.4 lets ordinary React/Vite source retain analyzable collection work inside `useMemo` while reusing the existing keyed-list selector and DOM identity model.
+
+### New in 0.7.4
+
+- Inline `useMemo` callbacks accept collection pipelines rooted in direct local array state.
+- Existing `filter`, direct-property `flatMap`, and `Array.from` selector analysis is reused without a browser memo cache.
+- Intermediate `.map()` calls lower to the existing `Array.from(source, mapper)` selector operation.
+- Memo locals are removed from emitted server modules after their uses are inlined, so state signals never execute array methods during rendering.
+- State updates preserve keyed row DOM identity while adding, removing, filtering, mapping, and reordering selected values.
+- Collection callbacks must be synchronous arrows with plain `(item)` or `(item, index)` identifier parameters; async, rest, default, and optional parameters fail with source locations.
+- The React/Vite fixture verifies `filter + map`, selector generation, browser updates, and retained identity for an existing row.
+
+### Boundary
+
+Memoized collections use the existing statically analyzable collection subset. Arbitrary callbacks, external captures, asynchronous transforms, getters, and general-purpose memo caching remain unsupported. React, a VDOM, hydration, and a retained browser component tree are not emitted.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.4
+```
+
 ## 0.7.3 - React memo normalization
 
 Kudzu 0.7.3 accepts common React memo authoring forms while preserving build-time components, direct state bindings, static HTML, and capability-only JavaScript.

package/framework/README.md

@@ -2,7 +2,9 @@
 
 Kudzu specializes ordinary common React-shaped TSX so migrations need minimal source restructuring. Declarative components, collection pipelines, conditions, hooks, and handlers should be lowered at build time rather than replaced with application-owned imperative DOM code. This principle applies across migrations and is not Stay-specific; it does not imply a React package, VDOM, hydration, or ecosystem runtime.
 
-Migration source may retain conventional `react` imports for supported named or aliased hooks, direct members such as `React.useState`, same-file `memo`, inline `useCallback`, direct-state expression `useMemo`, and default, namespace, or named `Fragment`. `build.mjs` canonicalizes those forms and rewrites module references to `@kudzujs/core` before build-time evaluation. Memo wrappers are erased or inlined because no browser component rerender or memo cache exists. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports.
+Migration source may retain conventional `react` imports for supported named or aliased hooks, direct members such as `React.useState`, same-file `memo`, inline `useCallback`, direct-state expression or analyzable collection-pipeline `useMemo`, and default, namespace, or named `Fragment`. `build.mjs` canonicalizes those forms and rewrites module references to `@kudzujs/core` before build-time evaluation. Memo wrappers are erased or inlined into existing bindings and keyed-list selectors because no browser component rerender or memo cache exists. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports.
+
+Direct `clsx` calls over literal strings, numbers, arrays, object conditions, and conditional expressions are similarly lowered to ordinary concatenation and conditional expressions. The package import is erased, and dynamic classes continue through the existing binding compiler without serializing or shipping the `clsx` function.
 
 - `build.mjs`: TSX compilation, static, `getStaticPaths`, and runtime-fallback routes, base paths, CSS collection, post-build hooks, behavior extraction, static HTML output, and the development server.
 - `core.mjs`: server-side JSX rendering, state slots, context providers, behavior metadata, and serializable capture validation.

package/framework/build.mjs

@@ -1744,6 +1744,53 @@ function hasReactModuleReference(source, file) {
   return found
 }
 
+function normalizeClsxSyntax(sourceFile, factory, context) {
+  const names = new Set()
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "clsx") continue
+    if (statement.importClause?.name) names.add(statement.importClause.name.text)
+    const bindings = statement.importClause?.namedBindings
+    if (bindings && ts.isNamedImports(bindings)) for (const entry of bindings.elements) if (!entry.isTypeOnly && (entry.propertyName ?? entry.name).text === "clsx") names.add(entry.name.text)
+  }
+  if (!names.size) return sourceFile
+
+  const lower = node => {
+    node = unwrapExpression(node)
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isNumericLiteral(node)) return node
+    if (node.kind === ts.SyntaxKind.FalseKeyword || node.kind === ts.SyntaxKind.NullKeyword) return factory.createStringLiteral("")
+    if (ts.isConditionalExpression(node)) return factory.updateConditionalExpression(node, node.condition, node.questionToken, lower(node.whenTrue), node.colonToken, lower(node.whenFalse))
+    if (ts.isArrayLiteralExpression(node)) return combine(node.elements.map(lower))
+    if (ts.isObjectLiteralExpression(node)) return combine(node.properties.map(property => {
+      if (!ts.isPropertyAssignment(property) || property.name && ts.isComputedPropertyName(property.name)) throw sourceNodeError(property, sourceFile, "clsx() object arguments require ordinary key/value properties")
+      const name = property.name
+      const value = name && (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) ? name.text : undefined
+      if (value === undefined) throw sourceNodeError(property, sourceFile, "clsx() object keys must be identifiers or literals")
+      return factory.createConditionalExpression(property.initializer, undefined, factory.createStringLiteral(value), undefined, factory.createStringLiteral(""))
+    }))
+    throw sourceNodeError(node, sourceFile, "clsx() arguments must be string/number literals, literal arrays, literal objects, or conditionals")
+  }
+  const combine = entries => entries.length ? entries.reduce((result, entry) => factory.createBinaryExpression(factory.createBinaryExpression(result, factory.createToken(ts.SyntaxKind.PlusToken), factory.createStringLiteral(" ")), factory.createToken(ts.SyntaxKind.PlusToken), entry)) : factory.createStringLiteral("")
+
+  const visitor = node => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && names.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) return combine(node.arguments.map(lower))
+    if (ts.isIdentifier(node) && names.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile) && !(ts.isCallExpression(node.parent) && node.parent.expression === node)) throw sourceNodeError(node, sourceFile, "clsx imports may only be called directly")
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "clsx") {
+      const clause = node.importClause
+      if (!clause || clause.isTypeOnly) return node
+      let bindings = clause.namedBindings
+      if (bindings && ts.isNamedImports(bindings)) {
+        const elements = bindings.elements.filter(entry => entry.isTypeOnly || (entry.propertyName ?? entry.name).text !== "clsx")
+        bindings = elements.length ? factory.updateNamedImports(bindings, elements) : undefined
+      }
+      const defaultName = clause.name && names.has(clause.name.text) ? undefined : clause.name
+      if (!defaultName && !bindings) return undefined
+      return factory.updateImportDeclaration(node, node.modifiers, factory.updateImportClause(clause, clause.isTypeOnly, defaultName, bindings), node.moduleSpecifier, node.attributes)
+    }
+    return ts.visitEachChild(node, visitor, context)
+  }
+  return ts.visitNode(sourceFile, visitor)
+}
+
 function normalizeReactMigrationSyntax(sourceFile, factory, context) {
   const supported = new Set(["createContext", "useContext", "useEffect", "useReducer", "useRef", "useState"])
   const erased = new Set(["memo", "useCallback", "useMemo"])
@@ -1799,7 +1846,7 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context) {
       if (!isLocalConst(node)) throw sourceNodeError(node, sourceFile, "React useMemo() local values must use const declarations")
       const callback = node.initializer.arguments[0]
       if (callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback))) {
-        const expression = reactMemoExpression(callback)
+        const expression = lowerReactMemoCollectionExpression(reactMemoExpression(callback), factory)
         const owner = nearestFunction(node)
         if (owner && expression) {
           const entries = memoLocals.get(owner) ?? new Map()
@@ -1835,6 +1882,15 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context) {
   const required = new Set()
   const imported = new Set()
   const visitor = node => {
+    if (ts.isVariableStatement(node)) {
+      const entries = memoLocals.get(nearestFunction(node))
+      if (entries) {
+        for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && entries.has(declaration.name.text) && declaration.initializer) ts.visitNode(declaration.initializer, visitor)
+        const declarations = node.declarationList.declarations.filter(declaration => !ts.isIdentifier(declaration.name) || !entries.has(declaration.name.text))
+        if (!declarations.length) return undefined
+        if (declarations.length !== node.declarationList.declarations.length) return factory.updateVariableStatement(node, node.modifiers, factory.updateVariableDeclarationList(node.declarationList, declarations.map(declaration => ts.visitEachChild(declaration, visitor, context))))
+      }
+    }
     if (ts.isIdentifier(node) && isReferenceIdentifier(node)) {
       const owner = nearestFunctionLike(node)
       const entry = memoLocals.get(owner)?.get(node.text)
@@ -1865,14 +1921,19 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context) {
         if (callback.parameters.length || callback.asteriskToken || callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) throw sourceNodeError(callback, sourceFile, "React useMemo() callback must be synchronous and parameterless")
         const dependency = node.arguments[1].elements.find(entry => !isReactCallbackDependency(entry))
         if (dependency) throw sourceNodeError(dependency, sourceFile, "React useMemo() dependencies must be identifiers or primitive literals")
-        const expression = reactMemoExpression(callback)
-        if (!expression || !isPureReactMemoExpression(expression)) throw sourceNodeError(callback.body, sourceFile, "React useMemo() callback must return one pure expression")
+        const expression = lowerReactMemoCollectionExpression(reactMemoExpression(callback), factory)
         const dependencies = new Set(node.arguments[1].elements.map(unwrapExpression).filter(ts.isIdentifier).map(entry => entry.text))
         const owner = nearestFunction(node)
         const states = owner ? ownerStateNames(owner) : new Set()
-        const unsupported = [...reactMemoReferenceNames(expression)].find(reference => !states.has(reference))
-        if (unsupported) throw sourceNodeError(expression, sourceFile, `React useMemo() pure expressions may only reference direct local state; found ${JSON.stringify(unsupported)}`)
-        const stale = [...states].find(state => referenceIdentifiers(expression, state).length && !dependencies.has(state))
+        const collectionState = expression && reactMemoCollectionState(expression, states, sourceFile)
+        if (!expression || !collectionState && !isPureReactMemoExpression(expression)) throw sourceNodeError(callback.body, sourceFile, "React useMemo() callback must return one pure expression or analyzable collection pipeline")
+        if (!collectionState) {
+          const unsupported = [...reactMemoReferenceNames(expression)].find(reference => !states.has(reference))
+          if (unsupported) throw sourceNodeError(expression, sourceFile, `React useMemo() pure expressions may only reference direct local state; found ${JSON.stringify(unsupported)}`)
+        }
+        const stale = collectionState
+          ? !dependencies.has(collectionState) ? collectionState : undefined
+          : [...states].find(state => referenceIdentifiers(expression, state).length && !dependencies.has(state))
         if (stale) throw sourceNodeError(node.arguments[1], sourceFile, `React useMemo() must list captured state ${JSON.stringify(stale)} as a dependency`)
         return ts.visitNode(expression, visitor)
       }
@@ -1889,6 +1950,7 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context) {
         const entries = []
         for (const entry of bindings.elements) {
           const name = (entry.propertyName ?? entry.name).text
+          if (entry.isTypeOnly) continue
           if (!entry.isTypeOnly && erased.has(name)) continue
           if (!entry.isTypeOnly && supported.has(name)) {
             if (imported.has(name)) continue
@@ -1941,6 +2003,27 @@ function reactMemoExpression(callback) {
   return callback.body.statements[0].expression
 }
 
+function lowerReactMemoCollectionExpression(expression, factory) {
+  if (!expression) return undefined
+  const visit = node => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && node.arguments.length === 1) {
+      return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("Array"), "from"), undefined, [visit(node.expression.expression), node.arguments[0]])
+    }
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ["filter", "flatMap"].includes(node.expression.name.text)) {
+      return factory.updateCallExpression(node, factory.updatePropertyAccessExpression(node.expression, visit(node.expression.expression), node.expression.name), node.typeArguments, node.arguments)
+    }
+    if (isArrayFromCall(node)) return factory.updateCallExpression(node, node.expression, node.typeArguments, [visit(node.arguments[0]), ...node.arguments.slice(1)])
+    return node
+  }
+  return visit(expression)
+}
+
+function reactMemoCollectionState(expression, states, sourceFile) {
+  const setters = new Map([...states].map(state => [state, state]))
+  const fail = (node, message) => { throw sourceNodeError(node, sourceFile, message) }
+  return renderedCollectionSource(expression, setters, undefined, fail, new Set())?.state?.text
+}
+
 function reactMemoComponentExpression(identifier, sourceFile, factory, context) {
   for (const statement of sourceFile.statements) {
     if (ts.isFunctionDeclaration(statement) && statement.name?.text === identifier.text && statement.body) {
@@ -1979,6 +2062,8 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
   return context => sourceFile => {
     const factory = context.factory
     const hasLinkElements = /<link/i.test(sourceFile.text)
+    sourceFile = normalizeClsxSyntax(sourceFile, factory, context)
+    ts.setParentRecursive(sourceFile, false)
     sourceFile = normalizeReactMigrationSyntax(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
@@ -1990,7 +2075,9 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     const importedSource = target => {
       let imported = importedSources.get(target)
       if (!imported) {
-        imported = normalizeReactMigrationSyntax(parseSourceFile(target, sourceIndex.get(target)), factory, context)
+        imported = normalizeClsxSyntax(parseSourceFile(target, sourceIndex.get(target)), factory, context)
+        ts.setParentRecursive(imported, false)
+        imported = normalizeReactMigrationSyntax(imported, factory, context)
         ts.setParentRecursive(imported, false)
         imported = normalizeRenderControlFlow(imported, factory, context)
         ts.setParentRecursive(imported, false)
@@ -2898,7 +2985,7 @@ function isArrayFromCall(value) {
 }
 
 function collectionParameters(callback, label, fail) {
-  if (!ts.isArrowFunction(callback) || callback.parameters.length < 1 || callback.parameters.length > 2 || callback.parameters.some(parameter => !ts.isIdentifier(parameter.name))) fail(callback, `${label} callback must be an arrow function with (item) or (item, index) identifier parameters`)
+  if (!ts.isArrowFunction(callback) || callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || callback.parameters.length < 1 || callback.parameters.length > 2 || callback.parameters.some(parameter => !ts.isIdentifier(parameter.name) || parameter.dotDotDotToken || parameter.initializer || parameter.questionToken)) fail(callback, `${label} callback must be a synchronous arrow function with (item) or (item, index) identifier parameters`)
   return { item: callback.parameters[0].name.text, index: callback.parameters[1]?.name.text }
 }
 

package/package.json

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