@kubb/renderer-jsx 5.0.0-beta.3 → 5.0.0-beta.30

package/src/components/Frontmatter.tsx

@@ -0,0 +1,38 @@
+import { stringify } from 'yaml'
+import type { Key, KubbReactElement } from '../types.ts'
+
+type Props = {
+  key?: Key
+  /**
+   * Plain object serialised as YAML between `---` fences.
+   *
+   * @example
+   * `data: { title: 'Pets', layout: 'doc' }`
+   */
+  data: Record<string, unknown>
+}
+
+/**
+ * Emits a YAML frontmatter envelope at the top of a generated markdown file.
+ *
+ * Renders a `<File.Source>` block containing `---\n<yaml>\n---`. Place it as
+ * the first child of `<File>` so it appears at the top of the output. Pair with
+ * `parserMd` to write `.md` files that downstream tooling (VitePress, MDX,
+ * static-site generators) treats as frontmatter.
+ *
+ * @example Page frontmatter at the top of a generated markdown file
+ * ```tsx
+ * <File baseName="pets.md" path="src/pets.md">
+ *   <Frontmatter data={{ title: 'Pets', layout: 'doc' }} />
+ *   <File.Source>
+ *     {'# Pets\n\nList of pets.'}
+ *   </File.Source>
+ * </File>
+ * ```
+ */
+export function Frontmatter({ data }: Props): KubbReactElement {
+  const envelope = `---\n${stringify(data).trimEnd()}\n---`
+  return <kubb-source name="frontmatter">{envelope}</kubb-source>
+}
+
+Frontmatter.displayName = 'Frontmatter'

package/src/components/Function.tsx

@@ -14,28 +14,28 @@ type Props = {
    * Requires `export` to also be `true`.
    * @default false
    */
-  default?: boolean
+  default?: boolean | null
   /**
    * Parameter list written verbatim between the function's parentheses.
    *
    * @example
    * `params: 'petId: string, options?: RequestOptions'`
    */
-  params?: string
+  params?: string | null
   /**
    * Emit the `export` keyword before the function declaration.
    * - `true` generates `export function name(…) { … }`
    * - `false` generates `function name(…) { … }`
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * 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
+  async?: boolean | null
   /**
    * TypeScript generic type parameters written verbatim between `<` and `>`.
    * Pass an array to emit multiple parameters separated by commas.
@@ -46,7 +46,7 @@ type Props = {
    * @example Multiple generics
    * `generics: ['TData', 'TError = unknown']`
    */
-  generics?: string | string[]
+  generics?: string | Array<string> | null
   /**
    * TypeScript return type annotation written verbatim after `:`.
    * When `async` is `true`, the value is automatically wrapped in `Promise<…>`.
@@ -54,12 +54,12 @@ type Props = {
    * @example
    * `returnType: 'Pet'`
    */
-  returnType?: string
+  returnType?: string | null
   /**
    * JSDoc block to prepend to the function declaration.
    * Each entry in `comments` becomes one line inside the emitted `/** … *\/` block.
    */
-  JSDoc?: JSDoc
+  JSDoc?: JSDoc | null
   /**
    * Child nodes rendered as the body of the function.
    */
@@ -110,7 +110,7 @@ type ArrowFunctionProps = Props & {
    * - `false` generates `const name = (…) => { … }`
    * @default false
    */
-  singleLine?: boolean
+  singleLine?: boolean | null
 }
 
 /**

package/src/components/Heading.tsx

@@ -0,0 +1,34 @@
+import type { Key, KubbReactElement } from '../types.ts'
+
+type Level = 1 | 2 | 3 | 4 | 5 | 6
+
+type Props = {
+  key?: Key
+  /**
+   * Heading depth, `1` through `6`. Matches the number of `#` characters
+   * prefixed to the heading text.
+   */
+  level: Level
+  /**
+   * Heading text. Inline markdown (links, emphasis) is passed through verbatim.
+   */
+  children: string
+}
+
+/**
+ * Renders an ATX-style markdown heading.
+ *
+ * Emits a `<File.Source>` block containing `${'#'.repeat(level)} ${children}`.
+ * Use inside a `<File>` rendered by `parserMd`.
+ *
+ * @example
+ * ```tsx
+ * <Heading level={2}>Installation</Heading>
+ * // ## Installation
+ * ```
+ */
+export function Heading({ level, children }: Props): KubbReactElement {
+  return <kubb-source name="heading">{`${'#'.repeat(level)} ${children}`}</kubb-source>
+}
+
+Heading.displayName = 'Heading'

package/src/components/List.tsx

@@ -0,0 +1,40 @@
+import type { Key, KubbReactElement } from '../types.ts'
+
+type Props = {
+  key?: Key
+  /**
+   * When `true`, emits a numbered list (`1. …`). When `false` or omitted,
+   * emits a bullet list (`- …`).
+   *
+   * @default false
+   */
+  ordered?: boolean | null
+  /**
+   * One entry per line. Inline markdown is passed through verbatim.
+   */
+  items: ReadonlyArray<string>
+}
+
+/**
+ * Renders a markdown list.
+ *
+ * Emits a `<File.Source>` block containing one entry per line, prefixed with
+ * `1.` / `2.` … when `ordered`, or `-` otherwise.
+ *
+ * @example
+ * ```tsx
+ * <List items={['Add the parser', 'Render the page']} />
+ * // - Add the parser
+ * // - Render the page
+ *
+ * <List ordered items={['First', 'Second']} />
+ * // 1. First
+ * // 2. Second
+ * ```
+ */
+export function List({ ordered, items }: Props): KubbReactElement {
+  const body = items.map((item, index) => `${ordered ? `${index + 1}.` : '-'} ${item}`).join('\n')
+  return <kubb-source name="list">{body}</kubb-source>
+}
+
+List.displayName = 'List'

package/src/components/Paragraph.tsx

@@ -0,0 +1,28 @@
+import type { Key, KubbReactElement } from '../types.ts'
+
+type Props = {
+  key?: Key
+  /**
+   * Paragraph text. Inline markdown (links, emphasis, code spans) is passed
+   * through verbatim.
+   */
+  children: string
+}
+
+/**
+ * Renders a markdown paragraph.
+ *
+ * Emits a `<File.Source>` block containing the text as-is. Paragraphs are
+ * separated from surrounding blocks by blank lines via the parser's source
+ * joining.
+ *
+ * @example
+ * ```tsx
+ * <Paragraph>{'A pet object with `id` and `name` fields.'}</Paragraph>
+ * ```
+ */
+export function Paragraph({ children }: Props): KubbReactElement {
+  return <kubb-source name="paragraph">{children}</kubb-source>
+}
+
+Paragraph.displayName = 'Paragraph'

package/src/components/Type.tsx

@@ -16,12 +16,12 @@ type TypeProps = {
    * - `false` generates `type Name = …`
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * JSDoc block to prepend to the type alias declaration.
    * Each entry in `comments` becomes one line inside the emitted `/** … *\/` block.
    */
-  JSDoc?: JSDoc
+  JSDoc?: JSDoc | null
   /**
    * Child nodes rendered as the type expression on the right-hand side of the alias.
    */

package/src/constants.ts

@@ -5,20 +5,30 @@ import type { ElementNames } from './types.ts'
  */
 export const TEXT_NODE_NAME = '#text' as const
 
+export const KUBB_FILE = 'kubb-file' as const
+export const KUBB_SOURCE = 'kubb-source' as const
+export const KUBB_EXPORT = 'kubb-export' as const
+export const KUBB_IMPORT = 'kubb-import' as const
+export const KUBB_FUNCTION = 'kubb-function' as const
+export const KUBB_ARROW_FUNCTION = 'kubb-arrow-function' as const
+export const KUBB_CONST = 'kubb-const' as const
+export const KUBB_TYPE = 'kubb-type' as const
+export const KUBB_JSX = 'kubb-jsx' 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_EXPORT,
+  KUBB_FILE,
+  KUBB_SOURCE,
+  KUBB_IMPORT,
+  KUBB_FUNCTION,
+  KUBB_ARROW_FUNCTION,
+  KUBB_CONST,
+  KUBB_TYPE,
+  KUBB_JSX,
   'kubb-text',
   'kubb-root',
   'kubb-app',

package/src/createRenderer.tsx

@@ -1,93 +1,112 @@
 import type { FileNode } from '@kubb/ast'
 import { Runtime } from './Runtime.tsx'
+import { SyncRuntime } from './SyncRuntime.tsx'
 import type { KubbReactElement } from './types.ts'
 
-type Options = {
-  /**
-   * 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.
+ * Renderer factory that turns the JSX produced by a generator into
+ * `FileNode`s using React's reconciler under the hood. Pass as the `renderer`
+ * property on `defineGenerator`. Kubb core stays generic, with no hard
+ * dependency on `@kubb/renderer-jsx`.
  *
- * 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.
+ * Use this when generators rely on React features (hooks, suspense, context).
+ * For pure-function components, see {@link jsxRendererSync} for ~2-4× faster
+ * rendering.
  *
- * @example Basic usage
- * ```ts
- * import { createRenderer, File } from '@kubb/renderer-jsx'
+ * @example Wire up a JSX generator
+ * ```tsx
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } 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 const myGenerator = defineGenerator<PluginTs>({
+ *   name: 'types',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     return (
+ *       <File baseName="output.ts" path={`${ctx.root}/output.ts`}>
+ *         <Type node={node} resolver={ctx.resolver} />
+ *       </File>
+ *     )
+ *   },
+ * })
  * ```
  */
-export function createRenderer(options: Options = {}): Renderer {
-  const runtime = new Runtime(options)
-
+export const jsxRenderer = () => {
+  const runtime = new Runtime()
   return {
-    async render(Element) {
-      await runtime.render(Element)
+    async render(element: KubbReactElement) {
+      await runtime.render(element)
     },
     get files() {
       return runtime.nodes
     },
-    unmount(error) {
+    dispose() {
+      runtime.unmount()
+    },
+    unmount(error?: Error | number | null) {
       runtime.unmount(error)
     },
+    [Symbol.dispose]() {
+      this.dispose()
+    },
   }
 }
 
 /**
- * A renderer factory for generators that produce JSX output.
+ * Lightweight renderer that walks the JSX tree in a single recursive pass —
+ * no React reconciler, no scheduler. Drop-in replacement for
+ * {@link jsxRenderer} at roughly 2–4× the throughput.
  *
- * 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`.
+ * Constraints: every component must be a pure function. Hooks, suspense, and
+ * class components are not supported.
  *
- * @example
- * ```ts
- * import { jsxRenderer } from '@kubb/renderer-jsx'
+ * Use this for generators that produce large amounts of output and do not need
+ * React's runtime features. It also exposes `stream()` for incremental file
+ * emission.
+ *
+ * @example Drop-in faster renderer
+ * ```tsx
  * import { defineGenerator } from '@kubb/core'
+ * import { jsxRendererSync } from '@kubb/renderer-jsx'
  *
  * export const myGenerator = defineGenerator<PluginTs>({
- *   name: 'my-generator',
- *   renderer: jsxRenderer,
- *   schema(node, options) {
- *     return <File baseName="output.ts" path="src/output.ts">...</File>
+ *   name: 'types',
+ *   renderer: jsxRendererSync,
+ *   schema(node, ctx) {
+ *     return (
+ *       <File baseName="output.ts" path={`${ctx.root}/output.ts`}>
+ *         <Type node={node} resolver={ctx.resolver} />
+ *       </File>
+ *     )
  *   },
  * })
  * ```
+ *
+ * @example Stream files as they are produced
+ * ```tsx
+ * const renderer = jsxRendererSync()
+ * for (const file of renderer.stream(element)) {
+ *   await writeFile(file.path, file.sources[0])
+ * }
+ * ```
  */
-export const jsxRenderer: () => Renderer = () => createRenderer()
+export const jsxRendererSync = () => {
+  const runtime = new SyncRuntime()
+
+  return {
+    async render(element: KubbReactElement): Promise<void> {
+      runtime.render(element)
+    },
+    get files() {
+      return runtime.nodes
+    },
+    stream(element: KubbReactElement): Generator<FileNode> {
+      return runtime.stream(element)
+    },
+    dispose() {},
+    unmount(_error?: Error | number | null) {},
+    [Symbol.dispose]() {
+      this.dispose()
+    },
+  }
+}

package/src/dom.ts

@@ -6,14 +6,12 @@ import type { DOMElement, DOMNode, DOMNodeAttribute, TextNode } from './types.ts
  * The element has no attributes, no children, and no parent.
  */
 export const createNode = (nodeName: string): DOMElement => {
-  const node: DOMElement = {
+  return {
     nodeName: nodeName as DOMElement['nodeName'],
-    attributes: new Map(),
+    attributes: Object.create(null) as Record<string, DOMNodeAttribute>,
     childNodes: [],
-    parentNode: undefined,
+    parentNode: null,
   }
-
-  return node
 }
 
 /**
@@ -50,7 +48,6 @@ export const insertBeforeNode = (node: DOMElement, newChildNode: DOMNode, before
   const index = node.childNodes.indexOf(beforeChildNode)
   if (index >= 0) {
     node.childNodes.splice(index, 0, newChildNode)
-
     return
   }
 
@@ -62,7 +59,7 @@ export const insertBeforeNode = (node: DOMElement, newChildNode: DOMNode, before
  * Does nothing if `removeNode` is not a direct child of `node`.
  */
 export const removeChildNode = (node: DOMElement, removeNode: DOMNode): void => {
-  removeNode.parentNode = undefined
+  removeNode.parentNode = null
 
   const index = node.childNodes.indexOf(removeNode)
   if (index >= 0) {
@@ -74,32 +71,23 @@ 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)
+  node.attributes[key] = value
 }
 
 /**
  * Create a new {@link TextNode} with the given text value.
  */
 export const createTextNode = (text: string): TextNode => {
-  const node: TextNode = {
+  return {
     nodeName: TEXT_NODE_NAME,
     nodeValue: text,
-    parentNode: undefined,
+    parentNode: null,
   }
-
-  setTextNodeValue(node, text)
-
-  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)
-  }
-
   node.nodeValue = text
 }

package/src/index.ts

@@ -1,8 +1,14 @@
 export { createContext, inject, provide, unprovide } from '@internals/utils'
+export { Callout } from './components/Callout.tsx'
+export { CodeBlock } from './components/CodeBlock.tsx'
 export { Const } from './components/Const.tsx'
 export { File } from './components/File.tsx'
+export { Frontmatter } from './components/Frontmatter.tsx'
 export { Function } from './components/Function.tsx'
+export { Heading } from './components/Heading.tsx'
 export { Jsx } from './components/Jsx.tsx'
+export { List } from './components/List.tsx'
+export { Paragraph } from './components/Paragraph.tsx'
 export { Root } from './components/Root.tsx'
 export { Type } from './components/Type.tsx'
-export { createRenderer, jsxRenderer } from './createRenderer.tsx'
+export { jsxRenderer, jsxRendererSync } from './createRenderer.tsx'

package/src/types.ts

@@ -30,14 +30,15 @@ export type ElementNames =
   | 'kubb-app'
 
 type Node = {
-  parentNode: DOMElement | undefined
+  parentNode: DOMElement | null
   internal_static?: boolean
 }
 
 /**
  * Allowed attribute value types for DOM elements.
+ * `null` signals intentionally empty — the prop was explicitly cleared.
  */
-export type DOMNodeAttribute = boolean | string | number | Record<string, unknown> | Array<unknown>
+export type DOMNodeAttribute = boolean | string | number | null | Record<string, unknown> | Array<unknown>
 
 type TextName = '#text'
 
@@ -71,11 +72,11 @@ export type DOMElement = {
   /**
    * Key/value attributes passed as JSX props to this element.
    */
-  attributes: Map<string, DOMNodeAttribute>
+  attributes: Record<string, DOMNodeAttribute>
   /**
    * Ordered list of child nodes attached to this element.
    */
-  childNodes: DOMNode[]
+  childNodes: Array<DOMNode>
   internal_transform?: OutputTransformer
 
   // Internal properties
@@ -119,12 +120,12 @@ export type KubbTextProps = {
  * Represents a generated file.
  */
 export type KubbFileProps = {
-  id?: string
+  id?: string | null
   children?: KubbReactNode
   baseName: string
   path: string
-  override?: boolean
-  meta?: FileNode['meta']
+  override?: boolean | null
+  meta?: FileNode['meta'] | null
 }
 
 /**