Merge pull request #524 from Simon-He95/feat/react-local-component-maps

feat(react): add direct streaming and HTML component maps

Author: Simon-He95

docs/.vitepress/twoslash/markstream-react.d.ts

@@ -1,6 +1,31 @@
-import type { ComponentType } from 'react'
+import type { ComponentType, PropsWithChildren, ReactNode } from 'react'
 import type { BaseNode } from 'stream-markdown-parser'
 
+export type RenderNodeFn = (node: BaseNode, key: string | number, ctx: RenderContext) => ReactNode
+
+export interface RenderContext {
+  customId?: string
+  isDark?: boolean
+  final?: boolean
+}
+
+export interface NodeComponentProps<TNode = unknown> {
+  node: TNode
+  ctx?: RenderContext
+  renderNode?: RenderNodeFn
+  indexKey?: string | number
+  customId?: string
+  isDark?: boolean
+  typewriter?: boolean
+  fade?: boolean
+  children?: ReactNode
+}
+
+export type StreamingComponent<TNode = any> = ComponentType<NodeComponentProps<TNode>>
+export type StreamingComponentMap = Record<string, StreamingComponent<any>>
+export type HtmlComponent<P extends object = any> = ComponentType<PropsWithChildren<P>>
+export type HtmlComponentMap = Record<string, HtmlComponent<any>>
+
 export interface NodeRendererProps {
   content?: string
   nodes?: BaseNode[]
@@ -14,6 +39,8 @@ export interface NodeRendererProps {
 
 export declare const MarkdownRender: ComponentType<NodeRendererProps>
 export declare const NodeRenderer: ComponentType<NodeRendererProps>
+export declare function defineStreamingComponents<const T extends Record<string, ComponentType<any>>>(components: T): T
+export declare function defineHtmlComponents<const T extends Record<string, ComponentType<any>>>(components: T): T
 export declare function setMermaidWorker(worker: Worker): void
 export declare function setKaTeXWorker(worker: Worker): void
 export declare function enableMermaid(): void

docs/guide/react-components.md

@@ -2,7 +2,7 @@
 
 markstream-react provides the same powerful components as markstream-vue, but built for React. All components support React 18+ with full TypeScript support.
 
-The root `markstream-react`, `markstream-react/next`, and `markstream-react/server` entrypoints all ship declaration files. Shared renderer and component types such as `NodeRendererProps`, `NodeRendererCodeBlockProps`, `NodeComponentProps`, `RenderContext`, `RenderNodeFn`, `CustomComponentMap`, `CodeBlockMonacoOptions`, `MarkdownCodeBlockNodeProps`, `ListItemNodeProps`, `HtmlPreviewFrameProps`, `TooltipProps`, `TooltipPlacement`, and `LinkNodeStyleProps` can be imported directly from the entrypoint you use.
+The root `markstream-react`, `markstream-react/next`, and `markstream-react/server` entrypoints all ship declaration files. Shared renderer and component types such as `NodeRendererProps`, `NodeRendererCodeBlockProps`, `NodeComponentProps`, `StreamingComponentMap`, `HtmlComponentMap`, `RenderContext`, `RenderNodeFn`, `CustomComponentMap`, `CodeBlockMonacoOptions`, `MarkdownCodeBlockNodeProps`, `ListItemNodeProps`, `HtmlPreviewFrameProps`, `TooltipProps`, `TooltipPlacement`, and `LinkNodeStyleProps` can be imported directly from the entrypoint you use.
 ## Main Component: MarkdownRender
 
 The primary component for rendering markdown content in React.
@@ -21,6 +21,8 @@ The primary component for rendering markdown content in React.
 | `final` | `boolean` | `false` | Marks end-of-stream; stops emitting streaming `loading` nodes |
 | `parseOptions` | `ParseOptions` | - | Parser options and token hooks (only when `content` is provided) |
 | `customHtmlTags` | `readonly string[]` | - | HTML-like tags emitted as custom nodes (e.g. `thinking`) |
+| `streamingComponents` | `StreamingComponentMap` | - | Renderer-local HTML-like tag components that receive `NodeComponentProps` and are automatically added to the parser's effective `customHtmlTags` |
+| `htmlComponents` | `HtmlComponentMap` | - | Renderer-local HTML-like tag components for the raw/dynamic HTML path; components receive sanitized HTML attributes and `children` |
 | `htmlPolicy` | `'safe' \| 'escape' \| 'trusted'` | `'safe'` | Controls `html_block` / `html_inline` rendering. `safe` blocks active/embed/form tags, `escape` shows literal HTML text, and `trusted` restores the broader trusted HTML behavior while still stripping scripts and unsafe attrs. |
 | `customMarkdownIt` | `(md: MarkdownIt) => MarkdownIt` | - | Customize the internal MarkdownIt instance |
 | `debugPerformance` | `boolean` | `false` | Log parse/render timing and virtualization stats (dev only) |
@@ -148,6 +150,72 @@ This is markstream-react.`
 }
 ```
 
+## Custom HTML-like Components
+
+For new React code, prefer renderer-local component maps when your content contains HTML-like custom tags.
+
+Use `streamingComponents` when the component needs the parser-backed streaming node contract. Keys are normalized like `customHtmlTags`, automatically added to the parser's effective custom tag list, and work with incomplete tags while content is streaming.
+
+Use `htmlComponents` when the component should render through the raw/dynamic HTML path and receive sanitized HTML attributes plus `children`. Attribute values are converted to primitive prop values, but attribute names are preserved from the source HTML, so `class` remains `class`. These components may still rerender while content streams, but they do not receive `node.loading` or the parser node contract.
+
+For typed component definitions, prefer `defineStreamingComponents(...)` and `defineHtmlComponents(...)`. `StreamingComponentMap` and `HtmlComponentMap` describe the broad runtime map shape accepted by the renderer; the helper functions perform the per-entry contract checks that catch mixing parser-backed `NodeComponentProps` components into the HTML props path.
+
+```tsx
+import type { NodeComponentProps } from 'markstream-react'
+import type React from 'react'
+import MarkdownRender, { defineHtmlComponents, defineStreamingComponents } from 'markstream-react'
+
+interface DocumentLinkNode {
+  type: 'documentlink'
+  tag: 'documentlink'
+  attrs?: [string, string][]
+  content: string
+  loading?: boolean
+}
+
+function getAttr(attrs: [string, string][] | undefined, name: string) {
+  return attrs?.find(([key]) => key === name)?.[1]
+}
+
+function DocumentLink({ node }: NodeComponentProps<DocumentLinkNode>) {
+  return (
+    <a
+      href={`/documents/${getAttr(node.attrs, 'id')}`}
+      aria-busy={node.loading || undefined}
+    >
+      {node.content}
+    </a>
+  )
+}
+
+function Badge({ kind, children }: React.PropsWithChildren<{ kind?: string }>) {
+  return <span data-kind={kind}>{children}</span>
+}
+
+const streamingComponents = defineStreamingComponents({
+  documentlink: DocumentLink,
+})
+
+const htmlComponents = defineHtmlComponents({
+  badge: Badge,
+})
+
+function App({ content, isDone }: { content: string, isDone: boolean }) {
+  return (
+    <MarkdownRender
+      content={content}
+      final={isDone}
+      streamingComponents={streamingComponents}
+      htmlComponents={htmlComponents}
+    />
+  )
+}
+```
+
+`customHtmlTags` remains available as a lower-level parser option. `htmlComponents` can also handle tags listed in `customHtmlTags`, but it still receives sanitized HTML attributes and `children`; only `streamingComponents` receives `NodeComponentProps`. `setCustomComponents` and `customId` remain supported for compatibility, shared application-level registration, and existing node overrides. If the same normalized tag appears in both `streamingComponents` and `htmlComponents`, `streamingComponents` wins and a development warning is emitted once.
+
+This API split fixes discoverability and typing around the two component contracts. HTML safety is still handled by `htmlPolicy` and the existing sanitization rules; the split is not a security boundary.
+
 ## Code Block Components
 
 ### MarkdownCodeBlockNode

docs/guide/react-markdown-migration.md

@@ -67,34 +67,77 @@ This means `components.h1` does not become `components.h1` again. It usually bec
 | `react-markdown` | `markstream-react` | Notes |
 |---|---|---|
 | `children` | `content` | Pass the Markdown string through `content`. |
-| `components` | `setCustomComponents(id?, mapping)` | `react-markdown` keys are HTML tags; `markstream-react` keys are node types such as `heading`, `link`, `paragraph`, `image`, `code_block`, `inline_code`. |
+| `components` | `streamingComponents`, `htmlComponents`, or `setCustomComponents(id?, mapping)` | For HTML-like custom tags, prefer renderer-local maps. Use `streamingComponents` for parser-backed `NodeComponentProps`; use `htmlComponents` for sanitized HTML attributes and `children`. Legacy node overrides still use `setCustomComponents`. |
 | `remarkPlugins` | `customMarkdownIt` | Use `markdown-it` plugins instead of `remark` plugins. Many common Markdown features already work without extra plugins. |
 | `remarkPlugins={[remarkGfm]}` | Often removable | Tables, task checkboxes, strikethrough, code fences, and other common constructs are already supported by the parser. Re-check edge cases before deleting plugin code. |
 | `rehypePlugins` | No direct equivalent | There is no public `rehype` stage. Use custom node renderers, `customHtmlTags`, `parseOptions`, or post-process `nodes` instead. |
-| `rehypeRaw` | Usually not needed | HTML-like tags are already parsed. For custom tags, prefer `customHtmlTags={['thinking']}` plus `setCustomComponents`. |
+| `rehypeRaw` | Usually not needed | HTML-like tags are already parsed. For custom tags, prefer `streamingComponents` or `htmlComponents` depending on the prop contract you need. |
 | `skipHtml` | No direct prop | HTML nodes render by default, with built-in blocking of dangerous attributes/tags and unsafe URLs in the HTML renderers. If you must remove HTML entirely, prefilter the input or parsed nodes yourself. |
 | `allowedElements` / `disallowedElements` / `allowElement` | No direct prop | Filter the parsed `nodes` tree yourself, or replace specific node renderers. |
 | `unwrapDisallowed` | Manual node filtering | Implement this in your node post-processing step if you need it. |
 | `urlTransform` | `parseOptions.validateLink` + custom `link` renderer | `validateLink` is for allow/deny. If you need URL rewriting, do it in a custom `link` renderer or while post-processing nodes. |
 
 ## Upgrade note: custom HTML-like tags
 
-Current `markstream-react` releases no longer infer custom HTML tag names from `setCustomComponents(...)`. If your app renders model output such as `<DocumentLink id="...">title</DocumentLink>` and expects a custom component to receive `props.node`, add the tag to `customHtmlTags`:
+New applications should use renderer-local maps for HTML-like custom tags:
 
 ```tsx
+import type { NodeComponentProps } from 'markstream-react'
+import type React from 'react'
+import MarkdownRender from 'markstream-react'
+
+function DocumentLink({ node }: NodeComponentProps<any>) {
+  return <span>{node.content}</span>
+}
+
+function Badge({ kind, children }: React.PropsWithChildren<{ kind?: string }>) {
+  return <span data-kind={kind}>{children}</span>
+}
+
+const renderer = (
+  <MarkdownRender
+    content={content}
+    final={isDone}
+    streamingComponents={{ documentlink: DocumentLink }}
+    htmlComponents={{ badge: Badge }}
+  />
+)
+```
+
+`streamingComponents` selects the parser-backed streaming-node contract. Its keys are added to the parser's effective `customHtmlTags`, so incomplete tags can render with `node.attrs`, `node.content`, and `node.loading`.
+
+`htmlComponents` selects the raw/dynamic HTML contract. Components receive sanitized HTML attributes plus `children`, not `props.node`. Attribute values are converted to primitive prop values, but names are preserved from source HTML, so `class` stays `class`.
+
+`customHtmlTags` remains available as a lower-level parser option. `setCustomComponents` and `customId` remain supported for compatibility, shared application-level registration, and built-in node overrides.
+
+Migration example:
+
+```tsx
+// Before
 setCustomComponents('chat', {
   documentlink: DocumentLink,
 })
 
-React.createElement(MarkdownRender, {
-  customId: 'chat',
-  content,
-  final: isDone,
-  customHtmlTags: ['documentlink'],
-})
+const before = (
+  <MarkdownRender
+    customId="chat"
+    customHtmlTags={['documentlink']}
+    content={content}
+  />
+)
+
+// After
+const after = (
+  <MarkdownRender
+    content={content}
+    streamingComponents={{
+      documentlink: DocumentLink,
+    }}
+  />
+)
 ```
 
-Without `customHtmlTags`, the tag stays on the raw HTML dynamic rendering path. The component can still render, but it receives HTML-style props such as `{ id, children }` instead of `NodeComponentProps`, and it will not receive `node.loading` for streaming partial renders. This auto-inference removal was an undocumented breaking change for apps that relied on the previous behavior.
+Current `markstream-react` releases no longer infer custom HTML tag names from `setCustomComponents(...)`. Without `customHtmlTags` or `streamingComponents`, a complete custom-looking tag stays on the raw HTML dynamic rendering path and receives HTML-style props such as `{ id, children }`. This auto-inference removal was an undocumented breaking change for apps that relied on the previous behavior. The new local maps make that contract explicit in types.
 
 ## Migrating `components`
 
@@ -167,7 +210,7 @@ Useful node-type translations:
 - `p` -> `paragraph`
 - `img` -> `image`
 - `code` / `pre` -> `code_block` or `inline_code`
-- Custom HTML-like tags -> `customHtmlTags` + `setCustomComponents`
+- Custom HTML-like tags -> `streamingComponents` for `NodeComponentProps`, or `htmlComponents` for sanitized HTML attributes/children
 
 ## Migrating code highlighting
 
@@ -241,25 +284,24 @@ If your old `rehypeRaw` usage was mainly there to support custom tags such as `<
 
 ```tsx
 import type { NodeComponentProps } from 'markstream-react'
-import MarkdownRender, { setCustomComponents } from 'markstream-react'
+import MarkdownRender from 'markstream-react'
 
 function ThinkingNode({ node }: NodeComponentProps<any>) {
   return <aside className="thinking-box">{node.content}</aside>
 }
 
-setCustomComponents('chat', { thinking: ThinkingNode })
-
 export function Message({ markdown }: { markdown: string }) {
   return (
     <MarkdownRender
-      customId="chat"
       content={markdown}
-      customHtmlTags={['thinking']}
+      streamingComponents={{ thinking: ThinkingNode }}
     />
   )
 }
 ```
 
+This API split is about discoverability and typing. HTML safety is still handled by `htmlPolicy` and the existing sanitization rules; do not treat the component-map split as a security boundary.
+
 ## Streaming upgrade path
 
 You do not need to adopt streaming on day one. A practical migration path is:
@@ -293,7 +335,7 @@ For most chat streams, the simpler `content` + smooth streaming path is the firs
 
 - Replace `<Markdown>{markdown}</Markdown>` with `<MarkdownRender content={markdown} />`.
 - Import `markstream-react/index.css`.
-- Move `components` overrides into `setCustomComponents(customId, mapping)`.
+- Move custom HTML-like tags into `streamingComponents` or `htmlComponents`; keep `setCustomComponents(customId, mapping)` for existing node overrides and shared registrations.
 - Remove plugins that are now redundant before re-adding custom ones.
 - Re-check any `rehype`-based HTML filtering or transformation logic.
 - If your app renders incremental output, evaluate `content` + smooth streaming first; upgrade to `nodes` when you need AST control or external parsing.

docs/guide/react-next-ssr.md

@@ -27,6 +27,43 @@ export default function Page() {
 }
 ```
 
+Direct component maps contain React component functions, so keep them inside a local Client Component wrapper when you use `markstream-react/next` from an App Router Server Component. Server Components should only pass serializable props such as `content` into that wrapper, matching the [Next.js Client Component prop rules](https://nextjs.org/docs/app/api-reference/directives/use-client).
+
+```tsx
+// app/markdown-renderer.tsx
+'use client'
+
+import type { NodeComponentProps } from 'markstream-react/next'
+import MarkdownRender, { defineStreamingComponents } from 'markstream-react/next'
+
+function DocumentLink(props: NodeComponentProps<{ content: string }>) {
+  return <a>{props.node.content}</a>
+}
+
+const streamingComponents = defineStreamingComponents({
+  documentlink: DocumentLink,
+})
+
+export function ClientMarkdown({ content }: { content: string }) {
+  return (
+    <MarkdownRender
+      content={content}
+      final
+      streamingComponents={streamingComponents}
+    />
+  )
+}
+```
+
+```tsx
+// app/page.tsx
+import { ClientMarkdown } from './markdown-renderer'
+
+export default function Page() {
+  return <ClientMarkdown content="<DocumentLink>Open</DocumentLink>" />
+}
+```
+
 ## Pure Server Rendering with `markstream-react/server`
 
 ```tsx
@@ -41,6 +78,8 @@ export default function Page() {
 }
 ```
 
+The pure server entry does not create a Client Component boundary, so server files can pass `streamingComponents` and `htmlComponents` directly when the render should remain server-only.
+
 ## Custom Components and Custom Tags
 
 If you register overrides from a server file, prefer the server helpers so you avoid importing the root package side effects: