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

package/dist/index.d.ts

@@ -1,38 +1,110 @@
-import { n as __name } from "./chunk-CErwXX-a.js";
-import { C as inject, S as createContext, T as unprovide, a as JSDoc, h as KubbReactNode, m as KubbReactElement, o as Key, w as provide, x as Context } from "./types-C7FD9BLg.js";
-import { ExportNode, FileNode, ImportNode, SourceNode } from "@kubb/ast/types";
+import { n as __name } from "./chunk-Bb7HlUDG.js";
+import { a as JSDoc, h as KubbReactNode, m as KubbReactElement, o as Key } from "./types-BEu94Tb3.js";
+import { ExportNode, FileNode, ImportNode, SourceNode } from "@kubb/ast";
 import * as _$react from "react";
 
+//#region ../../internals/utils/src/context.d.ts
+/**
+ * Context type that carries type information about its value
+ * This is a branded symbol type that enables type-safe context usage
+ */
+type Context<T> = symbol & {
+  readonly __type: T;
+};
+/**
+ * Provides a value to descendant components (Vue 3 style)
+ *
+ * @example
+ * ```ts
+ * const ThemeKey = Symbol('theme')
+ * provide(ThemeKey, { color: 'blue' })
+ * ```
+ */
+declare function provide<T>(key: symbol | Context<T>, value: T): void;
+/**
+ * Injects a value provided by an ancestor component (Vue 3 style)
+ *
+ * @example
+ * ```ts
+ * const theme = inject(ThemeKey, { color: 'default' })
+ * ```
+ */
+declare function inject<T>(key: symbol | Context<T>, defaultValue?: T): T;
+/**
+ * Removes a provided value from the context stack (for cleanup)
+ * @internal
+ */
+declare function unprovide<T>(key: symbol | Context<T>): void;
+/**
+ * Creates a context key with a default value (React-style compatibility)
+ *
+ * @example
+ * ```ts
+ * const ThemeContext = createContext({ color: 'blue' })
+ * // ThemeContext is now typed as Context<{ color: string }>
+ * const theme = useContext(ThemeContext) // theme is { color: string }
+ * ```
+ */
+declare function createContext<T>(defaultValue: T): Context<T>;
+//#endregion
 //#region src/components/Const.d.ts
 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>
+ * ```
  */
 declare function Const({
   children,
@@ -45,33 +117,67 @@ declare namespace Const {
 //#region src/components/File.d.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;
 };
 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;
 };
 type BaseProps = BasePropsWithBaseName | BasePropsWithoutBaseName;
 type Props$2<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>
+ * ```
  */
 declare function File<TMeta extends object = object>({
   children,
@@ -85,13 +191,30 @@ declare namespace 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>
+ * ```
  */
 declare function FileSource({
   children,
@@ -104,10 +227,21 @@ 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'
+ * ```
  */
 declare function FileExport(props: FileExportProps): KubbReactElement;
 declare namespace FileExport {
@@ -117,9 +251,27 @@ type FileImportProps = Omit<ImportNode, 'kind'> & {
   key?: Key;
 };
 /**
- * File.Import
+ * Declares an import entry for the enclosing {@link File}.
  *
- * Declares an import entry for the current 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'
+ * ```
+ *
+ * @example Namespace import
+ * ```tsx
+ * <File.Import name="z" path="zod" isNameSpace />
+ * // import * as z from 'zod'
+ * ```
  */
 declare function FileImport(props: FileImportProps): KubbReactElement;
 declare namespace FileImport {
@@ -130,45 +282,80 @@ declare namespace FileImport {
 type Props$1 = {
   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}`)
+ * // }
+ * ```
  */
 declare function Function({
   children,
@@ -180,15 +367,25 @@ declare namespace Function {
 }
 type ArrowFunctionProps = Props$1 & {
   /**
-   * 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
+ * ```
  */
 declare function ArrowFunction({
   children,
@@ -235,20 +432,26 @@ declare namespace Jsx {
 //#region src/components/Root.d.ts
 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.
  */
 declare function Root({
   onError,
@@ -262,24 +465,50 @@ declare namespace Root {
 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>
+ * ```
  */
 declare function Type({
   children,
@@ -315,16 +544,76 @@ declare const OasContext: Context<unknown>;
 //#region src/createRenderer.d.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;
 };
+/**
+ * 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()
+ * ```
+ */
 declare 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>
+ *   },
+ * })
+ * ```
+ */
+declare const jsxRenderer: () => Renderer;
 //#endregion
-export { Const, File, Function, Jsx, KubbContext, OasContext, Root, Type, createContext, createRenderer, inject, provide, unprovide };
+export { Const, File, Function, Jsx, KubbContext, OasContext, Root, Type, createContext, createRenderer, inject, jsxRenderer, provide, unprovide };
 //# sourceMappingURL=index.d.ts.map