@kubb/renderer-jsx 5.0.0-alpha.34 → 5.0.0-alpha.36

package/dist/types-BEu94Tb3.d.ts

@@ -0,0 +1,176 @@
+import { n as __name } from "./chunk-Bb7HlUDG.js";
+import { ArrowFunctionNode, ConstNode, ExportNode, FileNode, FunctionNode, ImportNode, SourceNode, TypeNode } from "@kubb/ast";
+import React, { JSX, ReactNode } from "react";
+
+//#region src/types.d.ts
+/**
+ * React reconciliation key type.
+ * Used to uniquely identify elements in lists and conditional renders.
+ */
+type Key = string | number | bigint;
+/**
+ * All custom element names recognized by the Kubb JSX renderer.
+ * Each name maps to a corresponding AST node type emitted during code generation.
+ */
+type ElementNames = 'br' | 'div' | 'indent' | 'dedent' | 'kubb-jsx' | 'kubb-text' | 'kubb-file' | 'kubb-source' | 'kubb-import' | 'kubb-export' | 'kubb-function' | 'kubb-arrow-function' | 'kubb-const' | 'kubb-type' | 'kubb-root' | 'kubb-app';
+type Node = {
+  parentNode: DOMElement | undefined;
+  internal_static?: boolean;
+};
+/**
+ * Allowed attribute value types stored on a {@link DOMElement}.
+ * Corresponds to the range of prop values JSX components may pass to intrinsic elements.
+ */
+type DOMNodeAttribute = boolean | string | number | Record<string, unknown> | Array<unknown>;
+type TextName = '#text';
+/**
+ * A leaf DOM node that holds a raw text string.
+ * Created by the renderer whenever a JSX expression produces a plain string child.
+ */
+type TextNode = {
+  nodeName: TextName;
+  nodeValue: string;
+} & Node;
+/**
+ * Discriminated union of all virtual DOM nodes.
+ * Resolves to {@link TextNode} when `nodeName` is `'#text'`, or {@link DOMElement} for
+ * any named Kubb element.
+ */
+type DOMNode<T = {
+  nodeName: NodeNames;
+}> = T extends {
+  nodeName: infer U;
+} ? U extends '#text' ? TextNode : DOMElement : never;
+type OutputTransformer = (s: string, index: number) => string;
+/**
+ * A named element node in the Kubb virtual DOM tree.
+ * Holds attributes, child nodes, and optional lifecycle callbacks used by the renderer.
+ */
+type DOMElement = {
+  nodeName: ElementNames;
+  /**
+   * Key/value attributes passed as JSX props to this element.
+   */
+  attributes: Map<string, DOMNodeAttribute>;
+  /**
+   * Ordered list of child nodes attached to this element.
+   */
+  childNodes: DOMNode[];
+  internal_transform?: OutputTransformer;
+  isStaticDirty?: boolean;
+  staticNode?: DOMElement;
+  onComputeLayout?: () => void;
+  onRender?: () => void;
+  onImmediateRender?: () => void;
+} & Node;
+type NodeNames = ElementNames | TextName;
+/**
+ * React node type used throughout Kubb JSX components.
+ * Alias for React's `ReactNode`.
+ */
+type KubbReactNode = ReactNode;
+/**
+ * React element type returned by Kubb JSX components.
+ * Alias for `JSX.Element`.
+ */
+type KubbReactElement = JSX.Element;
+/**
+ * Props for the `<kubb-jsx>` intrinsic element.
+ * Embeds a raw JSX string verbatim in the generated source.
+ */
+type KubbJsxProps = {
+  children?: string;
+};
+/**
+ * Props for the `<kubb-text>` intrinsic element.
+ * Wraps arbitrary React children as plain text in the output.
+ */
+type KubbTextProps = {
+  children?: KubbReactNode;
+};
+/**
+ * Props for the `<kubb-file>` intrinsic element.
+ * Represents a generated file entry collected by the renderer.
+ */
+type KubbFileProps = {
+  id?: string;
+  children?: KubbReactNode;
+  baseName: string;
+  path: string;
+  override?: boolean;
+  meta?: FileNode['meta'];
+};
+/**
+ * Props for the `<kubb-source>` intrinsic element.
+ * Marks a block of source text associated with the enclosing file.
+ */
+type KubbSourceProps = Omit<SourceNode, 'kind'> & {
+  children?: KubbReactNode;
+};
+/**
+ * Props for the `<kubb-import>` intrinsic element.
+ * Declares an import entry for the enclosing file.
+ */
+type KubbImportProps = Omit<ImportNode, 'kind'> & {};
+/**
+ * Props for the `<kubb-export>` intrinsic element.
+ * Declares an export entry for the enclosing file.
+ */
+type KubbExportProps = Omit<ExportNode, 'kind'> & {};
+/**
+ * Props for the `<kubb-function>` intrinsic element.
+ * Describes a function declaration node in the generated output.
+ */
+type KubbFunctionProps = Omit<FunctionNode, 'kind'> & {
+  children?: KubbReactNode;
+};
+/**
+ * Props for the `<kubb-arrow-function>` intrinsic element.
+ * Describes an arrow function declaration node in the generated output.
+ */
+type KubbArrowFunctionProps = Omit<ArrowFunctionNode, 'kind'> & {
+  children?: KubbReactNode;
+};
+/**
+ * Props for the `<kubb-const>` intrinsic element.
+ * Describes a constant declaration node in the generated output.
+ */
+type KubbConstProps = Omit<ConstNode, 'kind'> & {
+  children?: KubbReactNode;
+};
+/**
+ * Props for the `<kubb-type>` intrinsic element.
+ * Describes a TypeScript type alias declaration node in the generated output.
+ */
+type KubbTypeProps = Omit<TypeNode, 'kind'> & {
+  children?: KubbReactNode;
+};
+/**
+ * Props forwarded to the HTML `<br>` element within intrinsic element declarations.
+ */
+type LineBreakProps = React.DetailedHTMLProps<React.HTMLAttributes<HTMLBRElement>, HTMLBRElement>;
+/**
+ * JSDoc block to attach to a generated declaration.
+ *
+ * Each string in `comments` becomes one line inside the emitted `/** … *\/` block.
+ *
+ * @example
+ * ```ts
+ * { comments: ['@description A pet object.', '@deprecated Use PetV2 instead.'] }
+ * // Emits:
+ * // /**
+ * //  * @description A pet object.
+ * //  * @deprecated Use PetV2 instead.
+ * //  *\/
+ * ```
+ */
+type JSDoc = {
+  /**
+   * Lines to emit inside the JSDoc block, in source order.
+   * Use standard JSDoc tags such as `@description`, `@deprecated`, `@see`, etc.
+   */
+  comments: Array<string>;
+};
+//#endregion
+export { KubbTextProps as _, JSDoc as a, TextNode as b, KubbConstProps as c, KubbFunctionProps as d, KubbImportProps as f, KubbSourceProps as g, KubbReactNode as h, ElementNames as i, KubbExportProps as l, KubbReactElement as m, DOMNode as n, Key as o, KubbJsxProps as p, DOMNodeAttribute as r, KubbArrowFunctionProps as s, DOMElement as t, KubbFileProps as u, KubbTypeProps as v, LineBreakProps as y };
+//# sourceMappingURL=types-BEu94Tb3.d.ts.map

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-import { _ as KubbTextProps, a as JSDoc, b as TextNode, c as KubbConstProps, d as KubbFunctionProps, f as KubbImportProps, g as KubbSourceProps, h as KubbReactNode, i as ElementNames, l as KubbExportProps, m as KubbReactElement, n as DOMNode, o as Key, p as KubbJsxProps, r as DOMNodeAttribute, s as KubbArrowFunctionProps, t as DOMElement, u as KubbFileProps, v as KubbTypeProps, x as Context, y as LineBreakProps } from "./types-C7FD9BLg.js";
-export { Context, DOMElement, DOMNode, DOMNodeAttribute, ElementNames, JSDoc, Key, KubbArrowFunctionProps, KubbConstProps, KubbExportProps, KubbFileProps, KubbFunctionProps, KubbImportProps, KubbJsxProps, KubbReactElement, KubbReactNode, KubbSourceProps, KubbTextProps, KubbTypeProps, LineBreakProps, TextNode };
+import { _ as KubbTextProps, a as JSDoc, b as TextNode, c as KubbConstProps, d as KubbFunctionProps, f as KubbImportProps, g as KubbSourceProps, h as KubbReactNode, i as ElementNames, l as KubbExportProps, m as KubbReactElement, n as DOMNode, o as Key, p as KubbJsxProps, r as DOMNodeAttribute, s as KubbArrowFunctionProps, t as DOMElement, u as KubbFileProps, v as KubbTypeProps, y as LineBreakProps } from "./types-BEu94Tb3.js";
+export { DOMElement, DOMNode, DOMNodeAttribute, ElementNames, JSDoc, Key, KubbArrowFunctionProps, KubbConstProps, KubbExportProps, KubbFileProps, KubbFunctionProps, KubbImportProps, KubbJsxProps, KubbReactElement, KubbReactNode, KubbSourceProps, KubbTextProps, KubbTypeProps, LineBreakProps, TextNode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/renderer-jsx",
-  "version": "5.0.0-alpha.34",
+  "version": "5.0.0-alpha.36",
   "description": "React integration for Kubb - JSX runtime and component-based code generation with React reconciler for building type-safe generators",
   "keywords": [
     "react",
@@ -84,7 +84,7 @@
     }
   ],
   "dependencies": {
-    "@kubb/ast": "5.0.0-alpha.34"
+    "@kubb/ast": "5.0.0-alpha.36"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",

package/src/Runtime.tsx

@@ -1,5 +1,5 @@
 import { onProcessExit } from '@internals/utils'
-import type { FileNode } from '@kubb/ast/types'
+import type { FileNode } from '@kubb/ast'
 import { ConcurrentRoot } from 'react-reconciler/constants.js'
 import { Root } from './components/Root.tsx'
 import { createNode } from './dom.ts'
@@ -65,7 +65,6 @@ export class Runtime {
       null,
     )
 
-    // Unmount when process exits
     // Unmount when process exits
     this.unsubscribeExit = onProcessExit((code) => {
       this.unmount(code)
@@ -82,12 +81,12 @@ export class Runtime {
 
     const task = previous
       .catch(() => {})
-      .then(async () => {
+      .then(() => {
         if (this.#isUnmounted) {
           return
         }
 
-        const files = await processFiles(this.#rootNode)
+        const files = processFiles(this.#rootNode)
 
         this.nodes.push(...files)
 

package/src/components/Const.tsx

@@ -1,35 +1,63 @@
 import type { JSDoc, Key, KubbReactElement, KubbReactNode } from '../types.ts'
 
-export type ConstProps = {
+type ConstProps = {
   key?: Key
   /**
-   * Name of the const
+   * Identifier of the generated constant declaration.
+   *
+   * @example
+   * `name: 'petSchema'`
    */
   name: string
   /**
-   * Does this type need to be exported.
+   * Emit the `export` keyword before the `const` declaration.
+   * - `true` generates `export const name = …`
+   * - `false` generates `const name = …`
+   * @default false
    */
   export?: boolean
   /**
-   * Type to make the const being typed
+   * TypeScript type annotation for the constant, written verbatim after `const name:`.
+   *
+   * @example
+   * `type: 'Pet'` → `const pet: Pet = …`
    */
   type?: string
   /**
-   * Options for JSdocs.
+   * JSDoc block to prepend to the constant declaration.
+   * Each entry in `comments` becomes one line inside the emitted `/** … *\/` block.
    */
   JSDoc?: JSDoc
   /**
-   * Use of `const` assertions
+   * Append `as const` after the initialiser, enabling TypeScript const assertions.
+   * - `true` generates `const name = … as const`
+   * - `false` generates `const name = …`
+   * @default false
    */
   asConst?: boolean
   /**
-   * Children nodes.
+   * Child nodes rendered as the initialiser expression of the constant.
    */
   children?: KubbReactNode
 }
 
 /**
  * Generates a TypeScript constant declaration.
+ *
+ * @example Named export with type annotation
+ * ```tsx
+ * <Const export name="petSchema" type="z.ZodType<Pet>">
+ *   {`z.object({ id: z.number() })`}
+ * </Const>
+ * // export const petSchema: z.ZodType<Pet> = z.object({ id: z.number() })
+ * ```
+ *
+ * @example With JSDoc and const assertion
+ * ```tsx
+ * <Const name="HTTP_METHODS" asConst JSDoc={{ comments: ['@description Supported HTTP methods.'] }}>
+ *   {`['GET', 'POST', 'PUT', 'DELETE']`}
+ * </Const>
+ * ```
  */
 export function Const({ children, ...props }: ConstProps): KubbReactElement {
   const { name, export: canExport, type, JSDoc, asConst } = props

package/src/components/File.tsx

@@ -1,15 +1,22 @@
-import type { ExportNode, ImportNode, SourceNode } from '@kubb/ast/types'
+import type { ExportNode, ImportNode, SourceNode } from '@kubb/ast'
 import type { Key, KubbReactElement, KubbReactNode } from '../types.ts'
 
 type BasePropsWithBaseName = {
   /**
-   * Name to be used to dynamically create the baseName(based on input.path).
-   * Based on UNIX basename
+   * Base file name including extension, derived from the input path.
+   * Based on UNIX basename convention: `${name}${extname}`.
+   *
    * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
+   *
+   * @example
+   * `baseName: 'petStore.ts'`
    */
   baseName: `${string}.${string}`
   /**
-   * Path will be full qualified path to a specified file.
+   * Fully qualified path to the generated file.
+   *
+   * @example
+   * `path: 'src/models/petStore.ts'`
    */
   path: string
 }
@@ -17,7 +24,8 @@ type BasePropsWithBaseName = {
 type BasePropsWithoutBaseName = {
   baseName?: never
   /**
-   * Path will be full qualified path to a specified file.
+   * Fully qualified path to the generated file.
+   * Optional when `baseName` is omitted — the component renders its children inline.
    */
   path?: string
 }
@@ -26,14 +34,40 @@ type BaseProps = BasePropsWithBaseName | BasePropsWithoutBaseName
 
 type Props<TMeta> = BaseProps & {
   key?: Key
+  /**
+   * Arbitrary metadata attached to the file node.
+   * Used by plugins for barrel generation and custom post-processing.
+   */
   meta?: TMeta
+  /**
+   * Text prepended to the generated file content before any source blocks.
+   */
   banner?: string
+  /**
+   * Text appended to the generated file content after all source blocks.
+   */
   footer?: string
+  /**
+   * Child nodes rendered as the content of this file (source blocks, imports, exports).
+   */
   children?: KubbReactNode
 }
 
 /**
- * Adds files to the FileManager
+ * Declares a generated file entry to be collected by the renderer.
+ *
+ * When both `baseName` and `path` are provided, the component registers a new
+ * `FileNode` and passes its children through as source blocks.
+ * When either is omitted the children are rendered inline without creating a file entry.
+ *
+ * @example Basic file with a source block
+ * ```tsx
+ * <File baseName="petStore.ts" path="src/models/petStore.ts">
+ *   <File.Source name="Pet" isExportable isIndexable>
+ *     {`export type Pet = { id: number; name: string }`}
+ *   </File.Source>
+ * </File>
+ * ```
  */
 export function File<TMeta extends object = object>({ children, ...props }: Props<TMeta>): KubbReactElement {
   const { baseName, path } = props
@@ -49,14 +83,31 @@ File.displayName = 'File'
 
 type FileSourceProps = Omit<SourceNode, 'kind' | 'value'> & {
   key?: Key
+  /**
+   * Child nodes rendered as the source content of this block.
+   */
   children?: KubbReactNode
 }
 
 /**
- * File.Source
+ * Marks a block of source text to be associated with the enclosing {@link File}.
+ *
+ * Children are treated as the source string. When `isExportable` is `true` the
+ * `name` is used for deduplication and barrel generation.
  *
- * Marks a block of source text to be associated with the current file when
- * rendering with the FileCollector. Children are treated as the source string.
+ * @example Exportable, indexable source block
+ * ```tsx
+ * <File.Source name="Pet" isExportable isIndexable>
+ *   {`export type Pet = { id: number; name: string }`}
+ * </File.Source>
+ * ```
+ *
+ * @example Type-only source block
+ * ```tsx
+ * <File.Source name="PetId" isTypeOnly isExportable>
+ *   {`export type PetId = string`}
+ * </File.Source>
+ * ```
  */
 function FileSource({ children, ...props }: FileSourceProps): KubbReactElement {
   const { name, isExportable, isIndexable, isTypeOnly } = props
@@ -70,13 +121,24 @@ function FileSource({ children, ...props }: FileSourceProps): KubbReactElement {
 
 FileSource.displayName = 'FileSource'
 
-export type FileExportProps = Omit<ExportNode, 'kind'> & { key?: Key }
+type FileExportProps = Omit<ExportNode, 'kind'> & { key?: Key }
 
 /**
- * File.Export
+ * Declares an export entry for the enclosing {@link File}.
+ *
+ * The export is collected by the renderer and emitted at the top of the generated file.
  *
- * Declares an export entry for the current file. This will be collected by
- * the FileCollector for later emission.
+ * @example Named export
+ * ```tsx
+ * <File.Export name={['Pet']} path="./models/petStore" />
+ * // export { Pet } from './models/petStore'
+ * ```
+ *
+ * @example Type-only wildcard export
+ * ```tsx
+ * <File.Export path="./models/petStore" isTypeOnly />
+ * // export type * from './models/petStore'
+ * ```
  */
 function FileExport(props: FileExportProps): KubbReactElement {
   const { name, path, isTypeOnly, asAlias } = props
@@ -86,12 +148,30 @@ function FileExport(props: FileExportProps): KubbReactElement {
 
 FileExport.displayName = 'FileExport'
 
-export type FileImportProps = Omit<ImportNode, 'kind'> & { key?: Key }
+type FileImportProps = Omit<ImportNode, 'kind'> & { key?: Key }
 
 /**
- * File.Import
+ * Declares an import entry for the enclosing {@link File}.
+ *
+ * The import is collected by the renderer and emitted at the top of the generated file.
+ *
+ * @example Named import
+ * ```tsx
+ * <File.Import name={['useState']} path="react" />
+ * // import { useState } from 'react'
+ * ```
+ *
+ * @example Type-only import
+ * ```tsx
+ * <File.Import name={['Pet']} path="./models" isTypeOnly />
+ * // import type { Pet } from './models'
+ * ```
  *
- * Declares an import entry for the current file.
+ * @example Namespace import
+ * ```tsx
+ * <File.Import name="z" path="zod" isNameSpace />
+ * // import * as z from 'zod'
+ * ```
  */
 function FileImport(props: FileImportProps): KubbReactElement {
   const { name, root, path, isTypeOnly, isNameSpace } = props

package/src/components/Function.tsx

@@ -3,46 +3,81 @@ import type { JSDoc, Key, KubbReactElement, KubbReactNode } from '../types.ts'
 type Props = {
   key?: Key
   /**
-   * Name of the function.
+   * Identifier of the generated function declaration.
+   *
+   * @example
+   * `name: 'getPet'`
    */
   name: string
   /**
-   * Add default when export is being used
+   * Emit `default` after the `export` keyword, making this the module's default export.
+   * Requires `export` to also be `true`.
+   * @default false
    */
   default?: boolean
   /**
-   * Parameters/options/props that need to be used.
+   * Parameter list written verbatim between the function's parentheses.
+   *
+   * @example
+   * `params: 'petId: string, options?: RequestOptions'`
    */
   params?: string
   /**
-   * Does this function need to be exported.
+   * Emit the `export` keyword before the function declaration.
+   * - `true` generates `export function name(…) { … }`
+   * - `false` generates `function name(…) { … }`
+   * @default false
    */
   export?: boolean
   /**
-   * Does the function has async/promise behavior.
-   * This will also add `Promise<returnType>` as the returnType.
+   * Emit the `async` keyword, making this an async function.
+   * The return type is automatically wrapped in `Promise<returnType>` when both
+   * `async` and `returnType` are set.
+   * @default false
    */
   async?: boolean
   /**
-   * Generics that needs to be added for TypeScript.
+   * TypeScript generic type parameters written verbatim between `<` and `>`.
+   * Pass an array to emit multiple parameters separated by commas.
+   *
+   * @example Single generic
+   * `generics: 'TData'`
+   *
+   * @example Multiple generics
+   * `generics: ['TData', 'TError = unknown']`
    */
   generics?: string | string[]
   /**
-   * ReturnType(see async for adding Promise type).
+   * TypeScript return type annotation written verbatim after `:`.
+   * When `async` is `true`, the value is automatically wrapped in `Promise<…>`.
+   *
+   * @example
+   * `returnType: 'Pet'`
    */
   returnType?: string
   /**
-   * Options for JSdocs.
+   * JSDoc block to prepend to the function declaration.
+   * Each entry in `comments` becomes one line inside the emitted `/** … *\/` block.
    */
   JSDoc?: JSDoc
   /**
-   * Children nodes.
+   * Child nodes rendered as the body of the function.
    */
   children?: KubbReactNode
 }
 
 /**
  * Generates a TypeScript function declaration.
+ *
+ * @example Async exported function with generics
+ * ```tsx
+ * <Function export async name="getPet" generics={['TData = Pet']} params="petId: string" returnType="TData">
+ *   {`return client.get(\`/pets/\${petId}\`)`}
+ * </Function>
+ * // export async function getPet<TData = Pet>(petId: string): Promise<TData> {
+ * //   return client.get(`/pets/${petId}`)
+ * // }
+ * ```
  */
 export function Function({ children, ...props }: Props): KubbReactElement {
   const { name, default: isDefault, export: canExport, async: isAsync, generics, params, returnType, JSDoc } = props
@@ -70,16 +105,26 @@ Function.displayName = 'Function'
 
 type ArrowFunctionProps = Props & {
   /**
-   * Create Arrow function in one line
+   * Render the arrow function as a single-line expression (no braces around the body).
+   * - `true` generates `const name = (…) => expression`
+   * - `false` generates `const name = (…) => { … }`
+   * @default false
    */
   singleLine?: boolean
 }
 
 /**
- * ArrowFunction
+ * Generates an arrow function expression assigned to a `const`.
+ * Supports the same flags as {@link Function}.
+ * Use `singleLine` to render the body as a concise expression rather than a block.
  *
- * Renders an arrow function definition. Supports the same flags as `Function`.
- * Use `singleLine` to render the body as a single-line expression.
+ * @example Single-line arrow function
+ * ```tsx
+ * <Function.Arrow export name="double" params="n: number" returnType="number" singleLine>
+ *   {`n * 2`}
+ * </Function.Arrow>
+ * // export const double = (n: number): number => n * 2
+ * ```
  */
 function ArrowFunction({ children, ...props }: ArrowFunctionProps) {
   const { name, default: isDefault, export: canExport, async, generics, params, returnType, JSDoc, singleLine } = props

package/src/components/Root.tsx

@@ -31,23 +31,29 @@ class ErrorBoundary extends Component<{
   }
 }
 
-export type RootProps = {
+type RootProps = {
   /**
-   * Exit (unmount) the whole app.
+   * Callback invoked to unmount the entire renderer tree.
+   * Called with an `Error` when the exit is caused by a render error,
+   * or with `undefined` for a clean shutdown.
    */
   onExit: (error?: Error) => void
   /**
-   * Error hook receiving runtime exceptions.
+   * Callback invoked whenever a render error is caught by the error boundary.
+   * Use this to propagate errors up to the caller of {@link createRenderer}.
    */
   onError: (error: Error) => void
   /**
-   * Children nodes.
+   * Child nodes rendered inside the error boundary.
    */
   children?: KubbReactNode
 }
 
 /**
- * This component provides the root behavior for the Kubb runtime.
+ * Root component for the Kubb renderer tree.
+ *
+ * Wraps all children in an `ErrorBoundary` so that render errors are caught
+ * and forwarded to `onError` rather than crashing the process.
  */
 export function Root({ onError, children }: RootProps): KubbReactElement {
   return (