@kubb/renderer-jsx 5.0.0-beta.6 → 5.0.0-beta.61

package/src/SyncRuntime.tsx

@@ -0,0 +1,298 @@
+import type { ArrowFunctionNode, CodeNode, ExportNode, FileNode, ImportNode, JSDocNode, SourceNode } from '@kubb/ast'
+import * as factory from '@kubb/ast/factory'
+import { KUBB_ARROW_FUNCTION, KUBB_CONST, KUBB_EXPORT, KUBB_FILE, KUBB_FUNCTION, KUBB_IMPORT, KUBB_JSX, KUBB_SOURCE, KUBB_TYPE } from './constants.ts'
+import { Fragment } from './jsx-runtime.ts'
+import type { KubbReactElement } from './types.ts'
+
+type OnText = (text: string) => void
+type OnHost = (type: string, props: Record<string, unknown>) => void
+
+/**
+ * Walks `element`, resolving arrays, Fragments, and function components
+ * transparently, then calls `onText` for primitive values and `onHost` for
+ * every host element encountered. Pure function components are called
+ * synchronously. Hooks and class components are not supported.
+ */
+function walkElement(element: unknown, onText: OnText, onHost: OnHost): void {
+  if (element == null || typeof element === 'boolean') return
+
+  if (typeof element === 'string' || typeof element === 'number' || typeof element === 'bigint') {
+    onText(String(element))
+    return
+  }
+
+  if (Array.isArray(element)) {
+    for (const child of element) walkElement(child, onText, onHost)
+    return
+  }
+
+  if (typeof element === 'object' && '$$typeof' in element) {
+    const el = element as unknown as KubbReactElement
+    const { type } = el
+    const props = el.props as Record<string, unknown>
+
+    if (type === Fragment) {
+      walkElement(props['children'], onText, onHost)
+      return
+    }
+    if (typeof type === 'function') {
+      walkElement((type as (p: unknown) => unknown)(props), onText, onHost)
+      return
+    }
+    if (typeof type === 'string') {
+      onHost(type, props)
+    }
+  }
+}
+
+function toBool(val: unknown): boolean {
+  return (val ?? false) as boolean
+}
+
+function collectCodeNodes(props: Record<string, unknown>): Array<CodeNode> {
+  const nodes: Array<CodeNode> = []
+  collectCode(props['children'], nodes)
+  return nodes
+}
+
+function collectCode(element: unknown, nodes: Array<CodeNode>): void {
+  walkElement(
+    element,
+    (text) => {
+      if (text.trim()) nodes.push(factory.createText(text))
+    },
+    (type, props) => resolveCodeNode(type, props, nodes),
+  )
+}
+
+function resolveCodeNode(type: string, props: Record<string, unknown>, nodes: Array<CodeNode>): void {
+  if (type === 'br') {
+    nodes.push(factory.createBreak())
+    return
+  }
+
+  if (type === KUBB_JSX) {
+    let value = ''
+    walkElement(
+      props['children'],
+      (t) => {
+        value += t
+      },
+      () => {},
+    )
+    if (value) nodes.push(factory.createJsx(value))
+    return
+  }
+
+  if (type === KUBB_FUNCTION) {
+    nodes.push(
+      factory.createFunction({
+        name: props['name'] as string,
+        params: props['params'] as string | null | undefined,
+        export: props['export'] as boolean | null | undefined,
+        default: props['default'] as boolean | null | undefined,
+        async: props['async'] as boolean | null | undefined,
+        generics: props['generics'] as string | Array<string> | null | undefined,
+        returnType: props['returnType'] as string | null | undefined,
+        JSDoc: props['JSDoc'] as JSDocNode | null | undefined,
+        nodes: collectCodeNodes(props),
+      }),
+    )
+    return
+  }
+
+  if (type === KUBB_ARROW_FUNCTION) {
+    nodes.push(
+      factory.createArrowFunction({
+        name: props['name'] as string,
+        params: props['params'] as string | null | undefined,
+        export: props['export'] as boolean | null | undefined,
+        default: props['default'] as boolean | null | undefined,
+        async: props['async'] as boolean | null | undefined,
+        generics: props['generics'] as string | Array<string> | null | undefined,
+        returnType: props['returnType'] as string | null | undefined,
+        singleLine: props['singleLine'] as boolean | null | undefined,
+        JSDoc: props['JSDoc'] as JSDocNode | null | undefined,
+        nodes: collectCodeNodes(props),
+      } as Omit<ArrowFunctionNode, 'kind'>),
+    )
+    return
+  }
+
+  if (type === KUBB_CONST) {
+    nodes.push(
+      factory.createConst({
+        name: props['name'] as string,
+        type: props['type'] as string | null | undefined,
+        export: props['export'] as boolean | null | undefined,
+        asConst: props['asConst'] as boolean | null | undefined,
+        JSDoc: props['JSDoc'] as JSDocNode | null | undefined,
+        nodes: collectCodeNodes(props),
+      }),
+    )
+    return
+  }
+
+  if (type === KUBB_TYPE) {
+    nodes.push(
+      factory.createType({
+        name: props['name'] as string,
+        export: props['export'] as boolean | null | undefined,
+        JSDoc: props['JSDoc'] as JSDocNode | null | undefined,
+        nodes: collectCodeNodes(props),
+      }),
+    )
+    return
+  }
+}
+
+type FileChildren = { sources: Array<SourceNode>; exports: Array<ExportNode>; imports: Array<ImportNode> }
+
+function collectFileChildren(element: unknown): FileChildren {
+  const sources: Array<SourceNode> = []
+  const exports: Array<ExportNode> = []
+  const imports: Array<ImportNode> = []
+
+  walkElement(
+    element,
+    (text) => {
+      if (text.trim()) {
+        throw new Error(`[react] '${text}' should be part of <File.Source> component when using the <File/> component`)
+      }
+    },
+    (type, props) => {
+      if (type === KUBB_SOURCE) {
+        sources.push(
+          factory.createSource({
+            name: props['name']?.toString(),
+            isTypeOnly: toBool(props['isTypeOnly']),
+            isExportable: toBool(props['isExportable']),
+            isIndexable: toBool(props['isIndexable']),
+            nodes: collectCodeNodes(props),
+          }),
+        )
+        return
+      }
+
+      if (type === KUBB_EXPORT) {
+        exports.push(
+          factory.createExport({
+            name: props['name'] as ExportNode['name'],
+            path: props['path'] as string,
+            isTypeOnly: toBool(props['isTypeOnly']),
+            asAlias: toBool(props['asAlias']),
+          }),
+        )
+        return
+      }
+
+      if (type === KUBB_IMPORT) {
+        imports.push(
+          factory.createImport({
+            name: props['name'] as ImportNode['name'],
+            path: props['path'] as string,
+            root: props['root'] as string | null | undefined,
+            isTypeOnly: toBool(props['isTypeOnly']),
+            isNameSpace: toBool(props['isNameSpace']),
+          }),
+        )
+        return
+      }
+
+      const nested = collectFileChildren(props['children'])
+      sources.push(...nested.sources)
+      exports.push(...nested.exports)
+      imports.push(...nested.imports)
+    },
+  )
+
+  return { sources, exports, imports }
+}
+
+function* walkFiles(element: unknown): Generator<FileNode> {
+  if (element == null || typeof element === 'boolean') return
+
+  if (typeof element === 'string' || typeof element === 'number' || typeof element === 'bigint') return
+
+  if (Array.isArray(element)) {
+    for (const child of element) yield* walkFiles(child)
+    return
+  }
+
+  if (typeof element === 'object' && '$$typeof' in element) {
+    const el = element as unknown as KubbReactElement
+    const { type } = el
+    const props = el.props as Record<string, unknown>
+
+    if (type === Fragment) {
+      yield* walkFiles(props['children'])
+      return
+    }
+
+    if (typeof type === 'function') {
+      yield* walkFiles((type as (p: unknown) => unknown)(props))
+      return
+    }
+
+    if (typeof type === 'string') {
+      if (type === KUBB_FILE && props['baseName'] !== undefined && props['path'] !== undefined) {
+        const { sources, exports, imports } = collectFileChildren(props['children'])
+        yield {
+          baseName: props['baseName'],
+          path: props['path'],
+          meta: props['meta'] || {},
+          footer: props['footer'],
+          banner: props['banner'],
+          sources,
+          exports,
+          imports,
+        } as FileNode
+      } else {
+        yield* walkFiles(props['children'])
+      }
+    }
+  }
+}
+
+/**
+ * Synchronous JSX renderer that walks the element tree in a single pass,
+ * producing {@link FileNode} objects directly without an intermediate virtual
+ * DOM. No React fiber, scheduler, or work loop is involved.
+ *
+ * All components must be pure functions. Hooks and class components are not
+ * supported. Produces identical output to the React-backed {@link Runtime} at
+ * approximately 2, 4× the speed and a fraction of the allocations.
+ */
+export class SyncRuntime {
+  /**
+   * Accumulated {@link FileNode} results from every {@link render} call.
+   */
+  nodes: Array<FileNode> = []
+
+  /**
+   * Walks `element` synchronously, converts every `<kubb-file>` subtree into
+   * a {@link FileNode} with no intermediate virtual DOM, and appends the results
+   * to {@link nodes}.
+   */
+  render(element: KubbReactElement): void {
+    for (const file of walkFiles(element)) {
+      this.nodes.push(file)
+    }
+  }
+
+  /**
+   * Walks `element` synchronously and yields each {@link FileNode} as it is
+   * produced, without buffering into an intermediate array first. Callers can
+   * begin processing each file before the rest of the element tree is traversed.
+   *
+   * @example
+   * ```ts
+   * for (const file of runtime.stream(element)) {
+   *   await writeFile(file)
+   * }
+   * ```
+   */
+  *stream(element: KubbReactElement): Generator<FileNode> {
+    yield* walkFiles(element)
+  }
+}

package/src/components/Callout.tsx

@@ -0,0 +1,59 @@
+import type { Key, KubbReactElement } from '../types.ts'
+
+const CALLOUT_LABEL = {
+  tip: 'TIP',
+  note: 'NOTE',
+  important: 'IMPORTANT',
+  warning: 'WARNING',
+  caution: 'CAUTION',
+} as const
+
+export type CalloutType = keyof typeof CALLOUT_LABEL
+
+type Props = {
+  key?: Key
+  /**
+   * Callout kind. Maps to the uppercase label inside the `> [!TYPE]` marker.
+   */
+  type: CalloutType
+  /**
+   * Optional title rendered on the same line as the marker.
+   */
+  title?: string | null
+  /**
+   * Body text. Each line is quoted with `> ` so multi-line content stays
+   * inside the callout block.
+   */
+  children: string
+}
+
+/**
+ * Renders a GitHub-style alert callout, portable across GitHub, GitLab,
+ * VitePress, Obsidian, and MDX.
+ *
+ * Emits a `<File.Source>` block containing `> [!TYPE] Title` followed by the
+ * body with every line prefixed by `> `.
+ *
+ * @example
+ * ```tsx
+ * <Callout type="tip">Run `kubb start --watch` to keep the generator hot.</Callout>
+ * // > [!TIP]
+ * // > Run `kubb start --watch` to keep the generator hot.
+ *
+ * <Callout type="warning" title="Heads up">Breaking change in v6.</Callout>
+ * // > [!WARNING] Heads up
+ * // > Breaking change in v6.
+ * ```
+ */
+export function Callout({ type, title, children }: Props): KubbReactElement {
+  const label = CALLOUT_LABEL[type]
+  const header = title ? `> [!${label}] ${title}` : `> [!${label}]`
+  const quoted = children
+    .trimEnd()
+    .split('\n')
+    .map((line) => (line.length > 0 ? `> ${line}` : '>'))
+    .join('\n')
+  return <kubb-source name="callout">{`${header}\n${quoted}`}</kubb-source>
+}
+
+Callout.displayName = 'Callout'

package/src/components/Const.tsx

@@ -15,26 +15,26 @@ type ConstProps = {
    * - `false` generates `const name = …`
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * TypeScript type annotation for the constant, written verbatim after `const name:`.
    *
    * @example
    * `type: 'Pet'` → `const pet: Pet = …`
    */
-  type?: string
+  type?: string | null
   /**
    * JSDoc block to prepend to the constant declaration.
    * Each entry in `comments` becomes one line inside the emitted `/** … *\/` block.
    */
-  JSDoc?: JSDoc
+  JSDoc?: JSDoc | null
   /**
    * Append `as const` after the initialiser, enabling TypeScript const assertions.
    * - `true` generates `const name = … as const`
    * - `false` generates `const name = …`
    * @default false
    */
-  asConst?: boolean
+  asConst?: boolean | null
   /**
    * Child nodes rendered as the initialiser expression of the constant.
    */

package/src/components/File.tsx

@@ -25,9 +25,9 @@ type BasePropsWithoutBaseName = {
   baseName?: never
   /**
    * Fully qualified path to the generated file.
-   * Optional when `baseName` is omitted — the component renders its children inline.
+   * Optional when `baseName` is omitted, the component renders its children inline.
    */
-  path?: string
+  path?: string | null
 }
 
 type BaseProps = BasePropsWithBaseName | BasePropsWithoutBaseName
@@ -38,15 +38,17 @@ type Props<TMeta> = BaseProps & {
    * Arbitrary metadata attached to the file node.
    * Used by plugins for barrel generation and custom post-processing.
    */
-  meta?: TMeta
+  meta?: TMeta | null
   /**
    * Text prepended to the generated file content before any source blocks.
+   * Accepts `null` so `resolver.resolveBanner()` results can be passed directly.
    */
-  banner?: string
+  banner?: string | null
   /**
    * Text appended to the generated file content after all source blocks.
+   * Accepts `null` so `resolver.resolveFooter()` results can be passed directly.
    */
-  footer?: string
+  footer?: string | null
   /**
    * Child nodes rendered as the content of this file (source blocks, imports, exports).
    */

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 serialized 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/Jsx.tsx

@@ -17,7 +17,7 @@ type Props = {
  *
  * Use this component when you need to include JSX markup (including fragments
  * `<>…</>`) in the body of a generated function or component. The `children`
- * prop must be a plain string — expression attributes that reference runtime
+ * prop must be a plain string, expression attributes that reference runtime
  * values should be written as template literals.
  *
  * @example

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.
    */
@@ -31,7 +31,7 @@ type TypeProps = {
 /**
  * Generates a TypeScript type alias declaration.
  *
- * Throws if `name` does not start with an uppercase letter — TypeScript type aliases
+ * Throws if `name` does not start with an uppercase letter. TypeScript type aliases
  * should follow PascalCase naming conventions.
  *
  * @example Simple exported type alias