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

package/src/components/Type.tsx

@@ -1,27 +1,53 @@
 import type { JSDoc, Key, KubbReactElement, KubbReactNode } from '../types.ts'
 
-export type TypeProps = {
+type TypeProps = {
   key?: Key
   /**
-   * Name of the type, this needs to start with a capital letter.
+   * Identifier of the generated type alias.
+   * Must start with an uppercase letter to follow TypeScript naming conventions.
+   *
+   * @example
+   * `name: 'Pet'`
    */
   name: string
   /**
-   * Does this type need to be exported.
+   * Emit the `export` keyword before the type alias declaration.
+   * - `true` generates `export type Name = …`
+   * - `false` generates `type Name = …`
+   * @default false
    */
   export?: boolean
   /**
-   * Options for JSdocs.
+   * JSDoc block to prepend to the type alias declaration.
+   * Each entry in `comments` becomes one line inside the emitted `/** … *\/` block.
    */
   JSDoc?: JSDoc
   /**
-   * Children nodes.
+   * Child nodes rendered as the type expression on the right-hand side of the alias.
    */
   children?: KubbReactNode
 }
 
 /**
- * Generates a TypeScript type declaration.
+ * Generates a TypeScript type alias declaration.
+ *
+ * Throws if `name` does not start with an uppercase letter — TypeScript type aliases
+ * should follow PascalCase naming conventions.
+ *
+ * @example Simple exported type alias
+ * ```tsx
+ * <Type export name="PetId">
+ *   {`string | number`}
+ * </Type>
+ * // export type PetId = string | number
+ * ```
+ *
+ * @example Type alias with JSDoc
+ * ```tsx
+ * <Type export name="Pet" JSDoc={{ comments: ['@description A pet in the store.'] }}>
+ *   {`{ id: number; name: string }`}
+ * </Type>
+ * ```
  */
 export function Type({ children, ...props }: TypeProps): KubbReactElement {
   const { name, export: canExport, JSDoc } = props

package/src/constants.ts

@@ -0,0 +1,28 @@
+import type { ElementNames } from './types.ts'
+
+/**
+ * Name used for text-node entries in the virtual DOM.
+ */
+export const TEXT_NODE_NAME = '#text' as const
+
+/**
+ * Set of all element names recognized by the Kubb renderer.
+ * Used to distinguish Kubb-owned elements from unrecognized or text nodes during tree traversal.
+ */
+export const nodeNames = new Set<ElementNames>([
+  'kubb-export',
+  'kubb-file',
+  'kubb-source',
+  'kubb-import',
+  'kubb-function',
+  'kubb-arrow-function',
+  'kubb-const',
+  'kubb-type',
+  'kubb-jsx',
+  'kubb-text',
+  'kubb-root',
+  'kubb-app',
+  'br',
+  'indent',
+  'dedent',
+] as const)

package/src/context/KubbContext.ts

@@ -1,6 +1,6 @@
 import { createContext } from '@internals/utils'
 
-export type KubbContextValue = {
+type KubbContextValue = {
   driver: unknown
   plugin: unknown
   mode: 'single' | 'split'

package/src/createRenderer.tsx

@@ -1,20 +1,58 @@
-import type { FileNode } from '@kubb/ast/types'
+import type { FileNode } from '@kubb/ast'
 import { Runtime } from './Runtime.tsx'
 import type { KubbReactElement } from './types.ts'
 
 type Options = {
   /**
-   * Set this to true to always see the result of the render in the console(line per render)
+   * Print each render result to the console for debugging.
+   * Useful when diagnosing output differences between renders.
+   * @default false
    */
   debug?: boolean
 }
 
-export type Renderer = {
+/**
+ * The renderer instance returned by {@link createRenderer}.
+ */
+type Renderer = {
+  /**
+   * Render a JSX element tree and collect the resulting {@link FileNode} entries.
+   * Resolves once all synchronous render work (including React's flush) is done.
+   */
   render(Element: KubbReactElement): Promise<void>
+  /**
+   * Tear down the renderer and release all React resources.
+   * Pass an `Error` to signal an abnormal shutdown.
+   */
   unmount(error?: Error | number | null): void
+  /**
+   * The {@link FileNode} entries collected from the most recent `render` call.
+   */
   files: Array<FileNode>
 }
 
+/**
+ * Create a Kubb JSX renderer.
+ *
+ * The renderer converts a React JSX element tree — built from the components in this
+ * package — into an array of {@link FileNode} entries representing the generated files.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createRenderer, File } from '@kubb/renderer-jsx'
+ *
+ * const renderer = createRenderer()
+ * await renderer.render(
+ *   <File baseName="pet.ts" path="src/models/pet.ts">
+ *     <File.Source name="Pet" isExportable isIndexable>
+ *       {`export type Pet = { id: number; name: string }`}
+ *     </File.Source>
+ *   </File>
+ * )
+ * console.log(renderer.files) // [FileNode]
+ * renderer.unmount()
+ * ```
+ */
 export function createRenderer(options: Options = {}): Renderer {
   const runtime = new Runtime(options)
 
@@ -30,3 +68,26 @@ export function createRenderer(options: Options = {}): Renderer {
     },
   }
 }
+
+/**
+ * A renderer factory for generators that produce JSX output.
+ *
+ * Pass this as the `renderer` property of a `defineGenerator` call so that
+ * core can render the JSX element tree returned by your generator methods
+ * without a hard dependency on `@kubb/renderer-jsx`.
+ *
+ * @example
+ * ```ts
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ * import { defineGenerator } from '@kubb/core'
+ *
+ * export const myGenerator = defineGenerator<PluginTs>({
+ *   name: 'my-generator',
+ *   renderer: jsxRenderer,
+ *   schema(node, options) {
+ *     return <File baseName="output.ts" path="src/output.ts">...</File>
+ *   },
+ * })
+ * ```
+ */
+export const jsxRenderer: () => Renderer = () => createRenderer()

package/src/dom.ts

@@ -1,5 +1,10 @@
-import type { DOMElement, DOMNode, DOMNodeAttribute, ElementNames, TextNode } from './types.ts'
+import { TEXT_NODE_NAME } from './constants.ts'
+import type { DOMElement, DOMNode, DOMNodeAttribute, TextNode } from './types.ts'
 
+/**
+ * Create a new, empty {@link DOMElement} with the given node name.
+ * The element has no attributes, no children, and no parent.
+ */
 export const createNode = (nodeName: string): DOMElement => {
   const node: DOMElement = {
     nodeName: nodeName as DOMElement['nodeName'],
@@ -11,17 +16,30 @@ export const createNode = (nodeName: string): DOMElement => {
   return node
 }
 
+/**
+ * Append `childNode` as the last child of `node`.
+ *
+ * If `childNode` already has a parent, it is removed from that parent first
+ * (matching standard DOM move semantics).
+ * Text nodes (`nodeName === '#text'`) are silently ignored.
+ */
 export const appendChildNode = (node: DOMNode, childNode: DOMElement | DOMNode): void => {
   if (childNode.parentNode) {
     removeChildNode(childNode.parentNode, childNode)
   }
 
-  if (node.nodeName !== '#text') {
+  if (node.nodeName !== TEXT_NODE_NAME) {
     childNode.parentNode = node
     node.childNodes.push(childNode)
   }
 }
 
+/**
+ * Insert `newChildNode` before `beforeChildNode` in `node`'s child list.
+ *
+ * If `newChildNode` already has a parent, it is removed from that parent first.
+ * If `beforeChildNode` is not found, `newChildNode` is appended at the end.
+ */
 export const insertBeforeNode = (node: DOMElement, newChildNode: DOMNode, beforeChildNode: DOMNode): void => {
   if (newChildNode.parentNode) {
     removeChildNode(newChildNode.parentNode, newChildNode)
@@ -39,6 +57,10 @@ export const insertBeforeNode = (node: DOMElement, newChildNode: DOMNode, before
   node.childNodes.push(newChildNode)
 }
 
+/**
+ * Remove `removeNode` from `node`'s child list and clear its `parentNode` reference.
+ * Does nothing if `removeNode` is not a direct child of `node`.
+ */
 export const removeChildNode = (node: DOMElement, removeNode: DOMNode): void => {
   removeNode.parentNode = undefined
 
@@ -48,13 +70,19 @@ export const removeChildNode = (node: DOMElement, removeNode: DOMNode): void =>
   }
 }
 
+/**
+ * Set an attribute on `node`, storing it in the node's `attributes` map.
+ */
 export const setAttribute = (node: DOMElement, key: string, value: DOMNodeAttribute): void => {
   node.attributes.set(key, value)
 }
 
+/**
+ * Create a new {@link TextNode} with the given text value.
+ */
 export const createTextNode = (text: string): TextNode => {
   const node: TextNode = {
-    nodeName: '#text',
+    nodeName: TEXT_NODE_NAME,
     nodeValue: text,
     parentNode: undefined,
   }
@@ -64,6 +92,10 @@ export const createTextNode = (text: string): TextNode => {
   return node
 }
 
+/**
+ * Update the `nodeValue` of an existing {@link TextNode}.
+ * Non-string values are coerced to strings via `String(text)`.
+ */
 export const setTextNodeValue = (node: TextNode, text: string): void => {
   if (typeof text !== 'string') {
     text = String(text)
@@ -71,21 +103,3 @@ export const setTextNodeValue = (node: TextNode, text: string): void => {
 
   node.nodeValue = text
 }
-
-export const nodeNames = new Set<ElementNames>([
-  'kubb-export',
-  'kubb-file',
-  'kubb-source',
-  'kubb-import',
-  'kubb-function',
-  'kubb-arrow-function',
-  'kubb-const',
-  'kubb-type',
-  'kubb-jsx',
-  'kubb-text',
-  'kubb-root',
-  'kubb-app',
-  'br',
-  'indent',
-  'dedent',
-])

package/src/index.ts

@@ -7,4 +7,4 @@ export { Root } from './components/Root.tsx'
 export { Type } from './components/Type.tsx'
 export { KubbContext } from './context/KubbContext.ts'
 export { OasContext } from './context/OasContext.ts'
-export { createRenderer } from './createRenderer.tsx'
+export { createRenderer, jsxRenderer } from './createRenderer.tsx'

package/src/types.ts

@@ -1,9 +1,17 @@
-import type { ArrowFunctionNode, ConstNode, ExportNode, FileNode, FunctionNode, ImportNode, SourceNode, TypeNode } from '@kubb/ast/types'
+import type { ArrowFunctionNode, ConstNode, ExportNode, FileNode, FunctionNode, ImportNode, SourceNode, TypeNode } from '@kubb/ast'
 import type React from 'react'
 import type { JSX, ReactNode } from 'react'
 
+/**
+ * React reconciliation key type.
+ * Used to uniquely identify elements in lists and conditional renders.
+ */
 export 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.
+ */
 export type ElementNames =
   | 'br'
   | 'div'
@@ -27,14 +35,28 @@ type Node = {
   internal_static?: boolean
 }
 
-export type DOMNodeAttribute = boolean | string | number | Record<string, unknown>
+/**
+ * Allowed attribute value types stored on a {@link DOMElement}.
+ * Corresponds to the range of prop values JSX components may pass to intrinsic elements.
+ */
+export 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.
+ */
 export 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.
+ */
 export type DOMNode<T = { nodeName: NodeNames }> = T extends {
   nodeName: infer U
 }
@@ -45,9 +67,19 @@ export type DOMNode<T = { nodeName: NodeNames }> = T extends {
 
 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.
+ */
 export 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
 
@@ -61,17 +93,38 @@ export type DOMElement = {
 
 type NodeNames = ElementNames | TextName
 
+/**
+ * React node type used throughout Kubb JSX components.
+ * Alias for React's `ReactNode`.
+ */
 export type KubbReactNode = ReactNode
+
+/**
+ * React element type returned by Kubb JSX components.
+ * Alias for `JSX.Element`.
+ */
 export type KubbReactElement = JSX.Element
 
+/**
+ * Props for the `<kubb-jsx>` intrinsic element.
+ * Embeds a raw JSX string verbatim in the generated source.
+ */
 export type KubbJsxProps = {
   children?: string
 }
 
+/**
+ * Props for the `<kubb-text>` intrinsic element.
+ * Wraps arbitrary React children as plain text in the output.
+ */
 export type KubbTextProps = {
   children?: KubbReactNode
 }
 
+/**
+ * Props for the `<kubb-file>` intrinsic element.
+ * Represents a generated file entry collected by the renderer.
+ */
 export type KubbFileProps = {
   id?: string
   children?: KubbReactNode
@@ -80,34 +133,83 @@ export type KubbFileProps = {
   override?: boolean
   meta?: FileNode['meta']
 }
+
+/**
+ * Props for the `<kubb-source>` intrinsic element.
+ * Marks a block of source text associated with the enclosing file.
+ */
 export type KubbSourceProps = Omit<SourceNode, 'kind'> & {
   children?: KubbReactNode
 }
 
+/**
+ * Props for the `<kubb-import>` intrinsic element.
+ * Declares an import entry for the enclosing file.
+ */
 export type KubbImportProps = Omit<ImportNode, 'kind'> & {}
 
+/**
+ * Props for the `<kubb-export>` intrinsic element.
+ * Declares an export entry for the enclosing file.
+ */
 export type KubbExportProps = Omit<ExportNode, 'kind'> & {}
 
+/**
+ * Props for the `<kubb-function>` intrinsic element.
+ * Describes a function declaration node in the generated output.
+ */
 export 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.
+ */
 export type KubbArrowFunctionProps = Omit<ArrowFunctionNode, 'kind'> & {
   children?: KubbReactNode
 }
 
+/**
+ * Props for the `<kubb-const>` intrinsic element.
+ * Describes a constant declaration node in the generated output.
+ */
 export 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.
+ */
 export type KubbTypeProps = Omit<TypeNode, 'kind'> & {
   children?: KubbReactNode
 }
 
+/**
+ * Props forwarded to the HTML `<br>` element within intrinsic element declarations.
+ */
 export 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.
+ * //  *\/
+ * ```
+ */
 export type JSDoc = {
-  comments: string[]
+  /**
+   * Lines to emit inside the JSDoc block, in source order.
+   * Use standard JSDoc tags such as `@description`, `@deprecated`, `@see`, etc.
+   */
+  comments: Array<string>
 }
-
-export type { Context } from '@internals/utils'