渲染器 API

declare const createTemplateRenderer: (callerUrl: string, options?: TemplateRendererOptions) => TemplateRenderFn

interface TemplateRendererOptions {
  renderer?: Partial<RendererOptions> // 透传给 createRenderer 的覆盖项，在约定默认值之上合并
  bundledDir?: string // 生产打包产物目录（相对包根或绝对路径），默认按 main/exports 入口与目录扫描自动发现
}

type TemplateRenderFn = <K extends keyof LoadedRegistry & string>(
  templatePath: K,
  data: DataOf<LoadedRegistry[K]>,
  ctx?: RenderContextInput
) => Promise<RenderResult>

const renderTemplate = createTemplateRenderer(import.meta.url, {
  renderer: { outputDir: path.join(karinPathHtml, dir.pluginName) }
})

// 路由补全和 data 类型由注册表模块增强提供
const { success, htmlPath, error } = await renderTemplate('hello/card', {
  title: '你好',
  items: [{ label: '状态', value: 'ok' }]
})

import { createTemplateRenderer } from '@karinjs/template-react'
import path from 'node:path'

const renderTemplate = createTemplateRenderer(import.meta.url, {
  renderer: {
    outputDir: path.resolve(process.cwd(), 'output/screenshots')
  }
})

await renderTemplate('user/profile', { name: '张三', avatar: '...' })
// HTML 输出到 output/screenshots/user_profile.html

import { createTemplateRenderer } from '@karinjs/template-react'

const renderTemplate = createTemplateRenderer(import.meta.url)

// 深色模式渲染
await renderTemplate(
  'hello/card',
  { title: '夜间模式' },
  {
    theme: { mode: 'dark' }
  }
)

// 完整自定义主题
await renderTemplate(
  'hello/card',
  { title: '品牌定制' },
  {
    theme: {
      mode: 'light',
      accent: '#FF6B6B',
      accentForeground: '#FFFFFF',
      background: '#F8F9FA',
      foreground: '#212529',
      border: '#DEE2E6'
    }
  }
)

// 传入 CSS 变量
await renderTemplate(
  'hello/card',
  { title: '圆角定制' },
  {
    theme: {
      vars: { '--radius': '16px', '--spacing': '2rem' }
    }
  }
)

import { createTemplateRenderer } from '@karinjs/template-react'

const renderTemplate = createTemplateRenderer(import.meta.url)

await renderTemplate(
  'report/chart',
  { data: [120, 230, 180] },
  {
    scale: 2 // 2 倍渲染，截图更清晰
  }
)

import { createTemplateRenderer } from '@karinjs/template-react'

const renderTemplate = createTemplateRenderer(import.meta.url, {
  renderer: {
    htmlFileName: 'timestamp' // 每次渲染生成新文件
  }
})

// 并发渲染同一模板时不会相互覆盖
await Promise.all([renderTemplate('hello/card', { title: 'A' }), renderTemplate('hello/card', { title: 'B' })])
// 输出 hello_card_1723456789012.html 和 hello_card_1723456789123.html

import { createTemplateRenderer } from '@karinjs/template-react'

const renderTemplate = createTemplateRenderer(import.meta.url, {
  renderer: {
    htmlFileName: (templatePath) => {
      // 自定义规则：用横线分隔，加上日期前缀
      const date = new Date().toISOString().split('T')[0]
      return `${date}-${templatePath.replace('/', '-')}`
    }
  }
})

await renderTemplate('hello/card', { title: '...' })
// 输出 2026-08-14-hello-card.html

import { createTemplateRenderer } from '@karinjs/template-react'

const renderTemplate = createTemplateRenderer(import.meta.url, {
  renderer: {
    captureDir: undefined // 生产环境关闭捕获
  }
})

import { createTemplateRenderer } from '@karinjs/template-react'
import path from 'node:path'

const renderTemplate = createTemplateRenderer(import.meta.url, {
  renderer: {
    extraStylePaths: [path.resolve(process.cwd(), 'ktr/public/fonts.css'), path.resolve(process.cwd(), 'ktr/public/custom.css')]
  }
})
// fonts.css 和 custom.css 会内联到生成的 HTML <style> 中

import { createTemplateRenderer } from '@karinjs/template-react'
import type { RenderPlugin } from '@karinjs/template-react'

const logPlugin: RenderPlugin = {
  name: 'log-plugin',
  beforeRender: (ctx) => {
    console.log(`[渲染] ${ctx.path}`)
  },
  afterRender: (ctx) => {
    console.log(`[完成] ${ctx.path}, HTML 长度: ${ctx.html.length}`)
  }
}

const renderTemplate = createTemplateRenderer(import.meta.url, {
  renderer: {
    plugins: [logPlugin]
  }
})

import { createTemplateRenderer } from '@karinjs/template-react'

const renderTemplate = createTemplateRenderer(import.meta.url)

const result = await renderTemplate('hello/card', { title: 'Test' })

if (!result.success) {
  console.error(`渲染失败: ${result.error}`)
  // 可能的错误：
  // - Template is not registered: hello/card
  // - Template data validation failed: hello/card
  // - <React 渲染或写文件的原始异常消息>
} else {
  console.log(`渲染成功，HTML 路径: ${result.htmlPath}`)
}

declare const createRenderer: <R extends Record<keyof R, TemplateDef<any>>>(
  templates: R,
  options: RendererOptions
) => <K extends keyof R & string>(templatePath: K, data: DataOf<R[K]>, ctx?: RenderContextInput) => Promise<RenderResult>

declare const loadTemplateRegistry: (options?: LoadRegistryOptions) => Promise<LoadedRegistry>
declare const loadMockRegistry: <M extends Record<string, unknown> = Record<string, unknown>>(options?: LoadRegistryOptions) => Promise<M>

interface RenderContext {
  /** 当前渲染比例，截图模板通常保持为 1。 */
  scale: number
  /** 调用方显式提供的主题变量；框架不发明默认值。 */
  theme?: Partial<ThemeContext>
}

interface RenderPlugin {
  name: string // 插件名称
  enforce?: 'pre' | 'normal' | 'post' // 执行顺序，pre 先执行
  apply?: (path: string) => boolean // 返回 false 时跳过当前模板
  beforeRender?: (ctx: PluginContext) => void | Promise<void> // 生成 HTML 前执行
  afterRender?: (ctx: PluginContext & { html: string }) => string | void | Promise<string | void> // 加工 HTML
}