@kudzujs/core 0.7.13 → 0.7.14

package/README.md

@@ -10,7 +10,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.7.13 - Deterministic useId.** Ordinary React-shaped components can retain top-level `useId()` calls while Kudzu emits stable static HTML IDs and no browser capability. Read the [release notes](./RELEASES.md#0713---deterministic-useid) or open the [release page](https://kudzujs.cloud/releases/0.7.13).
+**Latest release: 0.7.14 - Intrinsic forwardRef.** Ordinary React-shaped components can retain direct `forwardRef()` wrappers while Kudzu separates ref from props and erases the wrapper into intrinsic output. Read the [release notes](./RELEASES.md#0714---intrinsic-forwardref) or open the [release page](https://kudzujs.cloud/releases/0.7.14).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)
@@ -78,7 +78,7 @@ ordinary React-shaped TSX
 ```
 
 - Function components execute at build time and do not survive as browser components.
-- `useState` and reduced `useReducer` compile to synchronous logical state and batched direct DOM writes; top-level `useId` becomes deterministic static HTML without browser JavaScript.
+- `useState` and reduced `useReducer` compile to synchronous logical state and batched direct DOM writes; top-level `useId` and direct intrinsic `forwardRef` authoring erase to static HTML without a component runtime.
 - Conditions, keyed collections, attributes, events, refs, effects, and supported component boundaries compile to route-specific capabilities.
 - Build-known data and routes become complete HTML through async components and `getStaticPaths()`.
 - Native document navigation is the default; static routes do not load a client runtime.

package/RELEASES.md

@@ -1,5 +1,29 @@
 # Kudzu Releases
 
+## 0.7.14 - Intrinsic forwardRef
+
+Kudzu 0.7.14 preserves conventional direct `forwardRef()` component authoring while erasing the wrapper into build-time intrinsic output.
+
+### New in 0.7.14
+
+- `forwardRef` may be imported directly or with an alias from `react`, or called as a direct default/namespace React member.
+- One top-level `const` component may wrap one inline synchronous `(props, ref)` render function.
+- The compiler removes `ref` from ordinary props and rest bindings before supplying it as the render function's second parameter.
+- The forwarded object ref must appear exactly once on the direct intrinsic root and reuses Kudzu's existing deterministic ref marker.
+- Components remain valid when the optional ref prop is omitted; `null` and `undefined` intrinsic refs emit no marker.
+- Same-file and relative-imported components compile without React, a wrapper function, hydration, or a browser component runtime.
+- Indirect callbacks, async/generator renders, callback or composed refs, fragments, component roots, nested targets, repeated forwarding, and `memo(forwardRef(...))` fail with source diagnostics.
+
+### Boundary
+
+This release intentionally supports one direct object-ref boundary. It does not add React ref objects, imperative handles, generic ref composition, or browser component instances. Existing keyed-row ownership checks still require refs used inside keyed lists to originate from that row.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.14
+```
+
 ## 0.7.13 - Deterministic useId
 
 Kudzu 0.7.13 preserves conventional top-level React `useId()` authoring while emitting deterministic static HTML IDs with no browser runtime.

package/framework/README.md

@@ -2,7 +2,7 @@
 
 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 or analyzable collection-pipeline `useMemo`, top-level `const` identifiers initialized by `useId()`, and default, namespace, or named `Fragment`. `useId()` becomes a deterministic build-time HTML ID and emits no browser capability; keyed rows reject it because cloned row templates cannot safely duplicate HTML IDs. Collection memos may start from local array state or a named relative import of an exported JSON-safe `const` array and may read direct local state declared in their dependency array. `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.
+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`, direct intrinsic `forwardRef`, top-level `const` identifiers initialized by `useId()`, and default, namespace, or named `Fragment`. `forwardRef()` accepts one inline synchronous `(props, ref)` function and requires the object ref exactly once on its direct intrinsic root; the compiler removes `ref` from props/rest and erases the wrapper. `useId()` becomes a deterministic build-time HTML ID and emits no browser capability; keyed rows reject it because cloned row templates cannot safely duplicate HTML IDs. Collection memos may start from local array state or a named relative import of an exported JSON-safe `const` array and may read direct local state declared in their dependency array. `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.
 

package/framework/build.mjs

@@ -1883,7 +1883,7 @@ function normalizeZustandMigrationSyntax(sourceFile, factory, context) {
 
 function normalizeReactMigrationSyntax(sourceFile, factory, context, importedCollections = new Set()) {
   const supported = new Set(["createContext", "useContext", "useEffect", "useId", "useReducer", "useRef", "useState"])
-  const erased = new Set(["memo", "useCallback", "useMemo"])
+  const erased = new Set(["forwardRef", "memo", "useCallback", "useMemo"])
   const aliases = new Map()
   const reactObjects = new Set()
   for (const statement of sourceFile.statements) {
@@ -1988,6 +1988,7 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context, importedCol
     }
     if (ts.isCallExpression(node)) {
       const name = migrationCallName(node)
+      if (name === "forwardRef") return ts.visitNode(lowerReactForwardRef(node, sourceFile, factory), visitor)
       if (name === "memo") {
         if (node.arguments.length !== 1 || !(ts.isArrowFunction(node.arguments[0]) || ts.isFunctionExpression(node.arguments[0]) || ts.isIdentifier(node.arguments[0]))) throw sourceNodeError(node, sourceFile, "React memo() requires exactly one function component or component identifier")
         if (ts.isIdentifier(node.arguments[0]) && isShadowedIdentifier(node.arguments[0], sourceFile)) throw sourceNodeError(node.arguments[0], sourceFile, "React memo() component identifiers must resolve to an unshadowed same-file top-level function")
@@ -2074,6 +2075,60 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context, importedCol
   return normalized
 }
 
+function lowerReactForwardRef(call, sourceFile, factory) {
+  const declaration = call.parent
+  const statement = declaration?.parent?.parent
+  if (!ts.isVariableDeclaration(declaration) || declaration.initializer !== call || !ts.isIdentifier(declaration.name) || !statement || !ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0 || statement.parent !== sourceFile) {
+    throw sourceNodeError(call, sourceFile, "React forwardRef() must directly initialize one top-level const component")
+  }
+  if (call.arguments.length !== 1 || !ts.isArrowFunction(call.arguments[0]) && !ts.isFunctionExpression(call.arguments[0])) throw sourceNodeError(call, sourceFile, "React forwardRef() requires exactly one inline render function")
+  const callback = call.arguments[0]
+  if (callback.asteriskToken || callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) throw sourceNodeError(callback, sourceFile, "React forwardRef() render function must be synchronous and cannot be a generator")
+  if (callback.parameters.length !== 2) throw sourceNodeError(callback, sourceFile, "React forwardRef() render function must declare exactly (props, ref)")
+  const [props, ref] = callback.parameters
+  if (props.dotDotDotToken || props.initializer || !ts.isIdentifier(props.name) && !ts.isObjectBindingPattern(props.name)) throw sourceNodeError(props, sourceFile, "React forwardRef() props must use one identifier or a flat object binding")
+  if (ref.dotDotDotToken || ref.initializer || !ts.isIdentifier(ref.name)) throw sourceNodeError(ref, sourceFile, "React forwardRef() ref parameter must be one identifier")
+
+  let elements
+  if (ts.isIdentifier(props.name)) {
+    elements = [
+      factory.createBindingElement(undefined, factory.createIdentifier("ref"), factory.createIdentifier(ref.name.text)),
+      factory.createBindingElement(factory.createToken(ts.SyntaxKind.DotDotDotToken), undefined, factory.createIdentifier(props.name.text))
+    ]
+  } else {
+    for (const element of props.name.elements) {
+      const property = (element.propertyName ?? element.name)
+      if (!ts.isIdentifier(element.name) || property.text === "ref") throw sourceNodeError(element, sourceFile, property.text === "ref" ? "React forwardRef() props must not declare ref; Kudzu supplies ref through the second parameter" : "React forwardRef() props must use one identifier or a flat object binding")
+    }
+    const rest = props.name.elements.findIndex(element => Boolean(element.dotDotDotToken))
+    elements = [...props.name.elements]
+    elements.splice(rest < 0 ? elements.length : rest, 0, factory.createBindingElement(undefined, factory.createIdentifier("ref"), factory.createIdentifier(ref.name.text)))
+  }
+
+  const last = ts.isBlock(callback.body) ? callback.body.statements.at(-1) : undefined
+  let returnCount = 0
+  const countReturns = node => {
+    if (node !== callback.body && isFunctionLike(node)) return
+    if (ts.isReturnStatement(node)) returnCount++
+    ts.forEachChild(node, countReturns)
+  }
+  countReturns(callback.body)
+  const returned = ts.isBlock(callback.body)
+    ? last && ts.isReturnStatement(last) ? last.expression : undefined
+    : callback.body
+  const root = returned && unwrapExpression(returned)
+  const tag = root && jsxTagName(root)
+  if ((ts.isBlock(callback.body) && returnCount !== 1) || !root || !ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root) || !ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) throw sourceNodeError(callback.body, sourceFile, "React forwardRef() render function must directly return one intrinsic JSX element")
+  const attributes = ts.isJsxElement(root) ? root.openingElement.attributes : root.attributes
+  const forwarded = attributes.properties.filter(attribute => ts.isJsxAttribute(attribute) && attribute.name.text === "ref" && ts.isJsxExpression(attribute.initializer) && ts.isIdentifier(attribute.initializer.expression) && attribute.initializer.expression.text === ref.name.text)
+  if (forwarded.length !== 1 || referenceIdentifiers(callback.body, ref.name.text).length !== 1) throw sourceNodeError(ref, sourceFile, "React forwardRef() ref must be forwarded exactly once as ref={ref} on the direct intrinsic root")
+
+  const parameter = factory.updateParameterDeclaration(props, props.modifiers, undefined, factory.createObjectBindingPattern(elements), props.questionToken, props.type, undefined)
+  return ts.isArrowFunction(callback)
+    ? factory.updateArrowFunction(callback, callback.modifiers, callback.typeParameters, [parameter], callback.type, callback.equalsGreaterThanToken, callback.body)
+    : factory.updateFunctionExpression(callback, callback.modifiers, undefined, callback.name, callback.typeParameters, [parameter], callback.type, callback.body)
+}
+
 function validateUseIdSyntax(sourceFile) {
   const imported = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && ["@kudzujs/core", "react"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useId"))
   if (!imported) return

package/framework/core.mjs

@@ -708,6 +708,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   for (const [rawName, value] of Object.entries(props)) {
     if (rawName === "children" || rawName === "key") continue
     if (rawName === "ref") {
+      if (value == null) continue
       if (!value?.[refMarker]) throw new Error("ref must be created by useRef(null)")
       if (renderContext.listDepth && !value.row) throw new Error("Refs in keyed lists must be declared by the keyed row component")
       attributes += ` data-k-ref="${value.id}"`

package/package.json

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