refactor(html)!: clarify renderer API names

Authored by an AI agent on behalf of Atinux; reviewed through the requested changes and automated checks.

Author: atinux

packages/comark-html/src/index.ts

@@ -1,8 +1,8 @@
 import type { ParserOptions, RendererOptions } from 'comark'
 import { createMarkdownParser } from 'comark'
-import { renderHtml } from './render.ts'
+import { renderHtmlFromDocument } from './render.ts'
 
-export { renderHtml } from './render.ts'
+export { renderHtmlFromDocument } from './render.ts'
 
 /**
  * Creates a reusable parse+render function with pre-configured options.
@@ -13,43 +13,43 @@ export { renderHtml } from './render.ts'
  *
  * @example
  * ```typescript
- * import { createRender } from '@comark/html'
- * import highlight from 'comark/plugins/highlight'
+ * import { createHtmlRenderer } from '@comark/html'
+ * import highlight from '@comark/html/plugins/highlight'
  *
- * const render = createRender({
+ * const renderHtml = createHtmlRenderer({
  *   plugins: [highlight()],
  *   components: {
- *     alert: ([, attrs, ...children], { render }) =>
- *       `<div class="alert alert-${attrs.type}">${render(children)}</div>`
+ *     alert: async ([, attrs, ...children], { render }) =>
+ *       `<div class="alert alert-${attrs.type}">${await render(children)}</div>`
  *   }
  * })
  *
- * const html = await render('# Hello\n\n**Bold** text.')
+ * const html = await renderHtml('# Hello\n\n**Bold** text.')
  * ```
  */
-export function createRender(options?: ParserOptions & RendererOptions): (markdown: string) => Promise<string> {
-  const parse = createMarkdownParser(options)
+export function createHtmlRenderer(options?: ParserOptions & RendererOptions): (markdown: string) => Promise<string> {
+  const parseMarkdown = createMarkdownParser(options)
   return async (markdown: string) => {
-    const tree = await parse(markdown)
-    return await renderHtml(tree, options as RendererOptions)
+    const document = await parseMarkdown(markdown)
+    return await renderHtmlFromDocument(document, options as RendererOptions)
   }
 }
 
 /**
  * Parse markdown and render it to an HTML string.
  *
- * @param markdown - The markdown/Comark content to render
+ * @param markdown - The markdown content to parse and render
  * @param options - Optional parse and render options
  * @returns A Promise resolving to the HTML string
  *
  * @example
  * ```typescript
- * import { render } from '@comark/html'
+ * import { renderHtml } from '@comark/html'
  *
- * const html = await render('# Hello\n\nThis is **bold** and _italic_.')
+ * const html = await renderHtml('# Hello\n\nThis is **bold** and _italic_.')
  * document.body.innerHTML = html
  * ```
  */
-export async function render(markdown: string, options?: RendererOptions): Promise<string> {
-  return createRender(options)(markdown)
+export async function renderHtml(markdown: string, options?: ParserOptions & RendererOptions): Promise<string> {
+  return createHtmlRenderer(options)(markdown)
 }

packages/comark-html/src/plugins/binding.ts

@@ -17,9 +17,9 @@ const escape = (s: string) =>
  * @example
  * ```ts
  * import binding, { Binding } from '@comark/html/plugins/binding'
- * import { createRender } from '@comark/html'
+ * import { createHtmlRenderer } from '@comark/html'
  *
- * const render = createRender({
+ * const renderHtml = createHtmlRenderer({
  *   plugins: [binding()],
  *   components: { Binding },
  * })

packages/comark-html/src/plugins/math.ts

@@ -12,9 +12,9 @@ export { default } from 'comark/plugins/math'
  * @example
  * ```typescript
  * import math, { Math } from '@comark/html/plugins/math'
- * import { createRender } from '@comark/html'
+ * import { createHtmlRenderer } from '@comark/html'
  *
- * const render = createRender({
+ * const renderHtml = createHtmlRenderer({
  *   plugins: [math()],
  *   components: { Math },
  * })

packages/comark-html/src/plugins/mermaid.ts

@@ -12,9 +12,9 @@ export { default } from 'comark/plugins/mermaid'
  * @example
  * ```typescript
  * import mermaid, { Mermaid } from '@comark/html/plugins/mermaid'
- * import { createRender } from '@comark/html'
+ * import { createHtmlRenderer } from '@comark/html'
  *
- * const render = createRender({
+ * const renderHtml = createHtmlRenderer({
  *   plugins: [mermaid()],
  *   components: { Mermaid },
  * })

packages/comark-html/src/render.ts

@@ -14,31 +14,31 @@ export interface RenderHTMLContext {
 export type ComponentRenderFn = (element: ElementNode, ctx: RenderHTMLContext) => string | Promise<string>
 
 /**
- * Render Comark tree to HTML
+ * Render a Markdown document to HTML.
  *
- * @param tree - The Comark tree to render
+ * @param document - The parsed Markdown document to render
  * @param options - Optional rendering options with custom components and data
  * @returns The HTML string
  *
  * @example
  * ```typescript
  * import { parseMarkdown } from 'comark'
- * import { renderHtml } from '@comark/html'
+ * import { renderHtmlFromDocument } from '@comark/html'
  *
- * const tree = await parseMarkdown('::alert{type="info"}\nHello!\n::')
+ * const document = await parseMarkdown('::alert{type="info"}\nHello!\n::')
  *
- * const html = renderHtml(tree, {
+ * const html = await renderHtmlFromDocument(document, {
  *   components: {
- *     alert: ([tag, attrs, ...children], { render }) => {
- *       return `<div class="alert alert-${attrs.type}">${render(children)}</div>`
+ *     alert: async ([tag, attrs, ...children], { render }) => {
+ *       return `<div class="alert alert-${attrs.type}">${await render(children)}</div>`
  *     }
  *   }
  * })
  * ```
  */
-export async function renderHtml(
-  tree: MarkdownDocument | { nodes: MarkdownDocument['nodes'] },
+export async function renderHtmlFromDocument(
+  document: MarkdownDocument | { nodes: MarkdownDocument['nodes'] },
   options?: RendererOptions
 ): Promise<string> {
-  return (await render(tree, { blockSeparator: '\n', format: 'text/html', ...options })).trim()
+  return (await render(document, { blockSeparator: '\n', format: 'text/html', ...options })).trim()
 }

packages/comark-html/test/github-alert.test.ts

@@ -1,11 +1,11 @@
 import { describe, it, expect } from 'vitest'
 import { parseMarkdown } from 'comark'
 import githubAlert from '@comark/html/plugins/alert'
-import { renderHtml } from '../src/index'
+import { renderHtmlFromDocument } from '../src/index'
 
 describe('githubAlert', () => {
   it('should convert !TIP to <svg> icon', async () => {
-    const tree = await parseMarkdown(
+    const doc = await parseMarkdown(
       `
 > [!NOTE]
 > Useful information that users should know, even when skimming content.
@@ -15,7 +15,7 @@ describe('githubAlert', () => {
         plugins: [githubAlert()],
       }
     )
-    const html = await renderHtml(tree)
+    const html = await renderHtmlFromDocument(doc)
     expect(html).toContain('<blockquote as="note">')
   })
 })