@incremark/react 0.1.2 → 0.2.1

package/dist/index.d.ts

@@ -1,8 +1,94 @@
 import { ParserOptions, AnimationEffect, TransformerPlugin, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, SourceBlock, TransformerOptions, DisplayBlock, BlockTransformer, RootContent } from '@incremark/core';
 export { AnimationEffect, BlockTransformer, DisplayBlock, IncrementalUpdate, ParsedBlock, ParserOptions, Root, RootContent, SourceBlock, TransformerOptions, TransformerPlugin, TransformerState, allPlugins, cloneNode, codeBlockPlugin, countChars, createBlockTransformer, createPlugin, defaultPlugins, imagePlugin, mathPlugin, mermaidPlugin, sliceAst, thematicBreakPlugin } from '@incremark/core';
+import React, { ReactNode } from 'react';
+import { Definition, FootnoteDefinition, RootContent as RootContent$1 } from 'mdast';
 import * as _incremark_devtools from '@incremark/devtools';
 import { DevToolsOptions } from '@incremark/devtools';
-import React from 'react';
+import { DesignTokens } from '@incremark/theme';
+export { DesignTokens, applyTheme, darkTheme, defaultTheme, generateCSSVars, mergeTheme } from '@incremark/theme';
+
+/**
+ * @file Definitions Context - 管理 Markdown 引用定义
+ *
+ * @description
+ * 提供 definitions 和 footnoteDefinitions 的 Context，
+ * 用于支持引用式图片/链接的解析和渲染。
+ *
+ * @author Incremark Team
+ * @license MIT
+ */
+
+/**
+ * Definitions Context 接口
+ */
+interface DefinitionsContextValue {
+    /** 图片/链接定义映射表 */
+    definitions: Record<string, Definition>;
+    /** 脚注定义映射表 */
+    footnoteDefinitions: Record<string, FootnoteDefinition>;
+    /** 脚注引用的出现顺序 */
+    footnoteReferenceOrder: string[];
+    /** 设置 definitions */
+    setDefinitions: (definitions: Record<string, Definition>) => void;
+    /** 设置 footnoteDefinitions */
+    setFootnoteDefinitions: (definitions: Record<string, FootnoteDefinition>) => void;
+    /** 设置 footnoteReferenceOrder */
+    setFootnoteReferenceOrder: (order: string[]) => void;
+    /** 清空 definitions */
+    clearDefinitions: () => void;
+    /** 清空 footnoteDefinitions */
+    clearFootnoteDefinitions: () => void;
+    /** 清空 footnoteReferenceOrder */
+    clearFootnoteReferenceOrder: () => void;
+    /** 清空所有定义 */
+    clearAllDefinitions: () => void;
+}
+/**
+ * Definitions Provider Props
+ */
+interface DefinitionsProviderProps {
+    children: ReactNode;
+}
+/**
+ * Definitions Provider 组件
+ *
+ * @description
+ * 为子组件提供 definitions 和 footnoteDefinitions。
+ * 通常在 useIncremark 返回的数据更新时，调用 setDefinitions 和 setFootnoteDefinitions。
+ *
+ * @example
+ * ```tsx
+ * import { DefinitionsProvider } from '@incremark/react'
+ *
+ * function App() {
+ *   return (
+ *     <DefinitionsProvider>
+ *       <Incremark blocks={blocks} />
+ *     </DefinitionsProvider>
+ *   )
+ * }
+ * ```
+ */
+declare const DefinitionsProvider: React.FC<DefinitionsProviderProps>;
+/**
+ * useDefinitions Hook
+ *
+ * @description
+ * 获取 definitions context。必须在 DefinitionsProvider 内部使用。
+ *
+ * @returns Definitions context value
+ *
+ * @throws 如果在 DefinitionsProvider 外部使用
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { definitions, footnoteDefinitions } = useDefinitions()
+ *   // 使用 definitions...
+ * }
+ * ```
+ */
+declare function useDefinitions(): DefinitionsContextValue;
 
 /** 打字机效果配置 */
 interface TypewriterOptions {
@@ -27,6 +113,7 @@ interface UseIncremarkOptions extends ParserOptions {
 }
 interface BlockWithStableId$1 extends ParsedBlock {
     stableId: string;
+    isLastPending?: boolean;
 }
 /** 打字机控制对象 */
 interface TypewriterControls {
@@ -58,10 +145,10 @@ interface TypewriterControls {
  *
  * function App() {
  *   // 基础用法
- *   const { blocks, append, finalize } = useIncremark()
+ *   const incremark = useIncremark()
  *
  *   // 启用打字机效果
- *   const { blocks, append, finalize, typewriter } = useIncremark({
+ *   const incremarkWithTypewriter = useIncremark({
  *     typewriter: {
  *       enabled: true,       // 可动态切换
  *       charsPerTick: [1, 3],
@@ -72,14 +159,9 @@ interface TypewriterControls {
  *   })
  *
  *   // 动态切换打字机效果
- *   typewriter.setEnabled(false)
+ *   incremarkWithTypewriter.typewriter.setEnabled(false)
  *
- *   return (
- *     <>
- *       <Incremark blocks={blocks} />
- *       {typewriter.isProcessing && <button onClick={typewriter.skip}>跳过</button>}
- *     </>
- *   )
+ *   return <Incremark incremark={incremark} />
  * }
  * ```
  */
@@ -96,6 +178,8 @@ declare function useIncremark(options?: UseIncremarkOptions): {
     blocks: BlockWithStableId$1[];
     /** 是否正在加载 */
     isLoading: boolean;
+    /** 是否已完成（finalize） */
+    isFinalized: boolean;
     /** 追加内容 */
     append: (chunk: string) => IncrementalUpdate;
     /** 完成解析 */
@@ -110,6 +194,8 @@ declare function useIncremark(options?: UseIncremarkOptions): {
     parser: IncremarkParser;
     /** 打字机控制 */
     typewriter: TypewriterControls;
+    /** @internal 提供给 Incremark 组件使用的 context value */
+    _definitionsContextValue: DefinitionsContextValue;
 };
 type UseIncremarkReturn = ReturnType<typeof useIncremark>;
 
@@ -207,7 +293,7 @@ interface BlockWithStableId extends ParsedBlock {
 }
 interface IncremarkProps {
     /** 要渲染的块列表 */
-    blocks: BlockWithStableId[];
+    blocks?: BlockWithStableId[];
     /** 自定义组件映射 */
     components?: Partial<Record<string, React.ComponentType<{
         node: any;
@@ -216,6 +302,8 @@ interface IncremarkProps {
     showBlockStatus?: boolean;
     /** 自定义类名 */
     className?: string;
+    /** 可选：useIncremark 返回的对象（用于自动提供 context） */
+    incremark?: UseIncremarkReturn;
 }
 /**
  * Incremark 主渲染组件
@@ -224,9 +312,10 @@ interface IncremarkProps {
  * ```tsx
  * import { useIncremark, Incremark } from '@incremark/react'
  *
+ * // 推荐用法: 传入 incremark 对象（自动提供 context）
  * function App() {
- *   const { blocks } = useIncremark()
- *   return <Incremark blocks={blocks} />
+ *   const incremark = useIncremark()
+ *   return <Incremark incremark={incremark} />
  * }
  * ```
  */
@@ -285,4 +374,119 @@ interface AutoScrollContainerRef {
  */
 declare const AutoScrollContainer: React.ForwardRefExoticComponent<AutoScrollContainerProps & React.RefAttributes<AutoScrollContainerRef>>;
 
-export { AutoScrollContainer, type AutoScrollContainerProps, type AutoScrollContainerRef, Incremark, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, type TypewriterControls, type TypewriterOptions, type UseBlockTransformerOptions, type UseBlockTransformerReturn, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useBlockTransformer, useDevTools, useIncremark };
+/**
+ * HtmlElementNode 类型定义（与 @incremark/core 中的定义一致）
+ */
+interface HtmlElementNode {
+    type: 'htmlElement';
+    tagName: string;
+    attrs: Record<string, string>;
+    children: RootContent$1[];
+    data?: {
+        rawHtml?: string;
+        parsed?: boolean;
+        originalType?: string;
+    };
+}
+interface IncremarkHtmlElementProps {
+    node: HtmlElementNode;
+}
+/**
+ * IncremarkHtmlElement 组件
+ *
+ * 渲染结构化的 HTML 元素节点
+ */
+declare const IncremarkHtmlElement: React.FC<IncremarkHtmlElementProps>;
+
+/**
+ * 脚注列表组件
+ *
+ * 在文档底部渲染所有脚注定义，按引用出现的顺序排列
+ *
+ * @component IncremarkFootnotes
+ *
+ * @remarks
+ * 样式定义在 @incremark/theme 中的 footnotes.less
+ * footnoteReferenceOrder 自动从 context 获取，无需手动传递
+ */
+
+/**
+ * IncremarkFootnotes 组件
+ *
+ * 渲染文档底部的脚注列表，支持：
+ * - 按引用出现顺序排列
+ * - 双向跳转（引用 ↔ 定义）
+ * - 高亮当前查看的脚注
+ *
+ * @example
+ * ```tsx
+ * <IncremarkFootnotes />
+ * ```
+ */
+declare const IncremarkFootnotes: React.FC;
+
+/**
+ * @file IncremarkContainerProvider - Incremark 容器级 Provider
+ *
+ * @description
+ * 用于在 Incremark 的渲染树根部统一注入各种 Context / 全局能力。
+ * 目前主要用于注入 DefinitionsContext（引用定义、脚注定义等）。
+ *
+ * 设计目标：
+ * - **对用户隐藏实现细节**：用户只需 `<Incremark incremark={incremark} />`
+ * - **为未来扩展留空间**：后续可在这里统一添加更多 Provider（主题、滚动、性能开关等）
+ *
+ * @author Incremark Team
+ * @license MIT
+ */
+
+/**
+ * IncremarkContainerProvider Props
+ */
+interface IncremarkContainerProviderProps {
+    /** 子节点 */
+    children: ReactNode;
+    /** DefinitionsContext 的值 */
+    definitions: DefinitionsContextValue;
+}
+/**
+ * IncremarkContainerProvider 组件
+ *
+ * @param props - 组件参数
+ * @returns ReactElement
+ */
+declare const IncremarkContainerProvider: React.FC<IncremarkContainerProviderProps>;
+
+interface ThemeProviderProps {
+    /** 主题配置，可以是：
+     * - 字符串：'default' | 'dark'
+     * - 完整主题对象：DesignTokens
+     * - 部分主题对象：Partial<DesignTokens>（会合并到默认主题）
+     */
+    theme: 'default' | 'dark' | DesignTokens | Partial<DesignTokens>;
+    /** 子组件 */
+    children: ReactNode;
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * ThemeProvider 组件
+ *
+ * 提供主题上下文，支持全局/局部主题和部分变量替换
+ *
+ * @example
+ * ```tsx
+ * // 使用预设主题
+ * <ThemeProvider theme="dark">
+ *   <Incremark blocks={blocks} />
+ * </ThemeProvider>
+ *
+ * // 部分替换
+ * <ThemeProvider theme={{ color: { text: { primary: '#custom' } } }}>
+ *   <Incremark blocks={blocks} />
+ * </ThemeProvider>
+ * ```
+ */
+declare const ThemeProvider: React.FC<ThemeProviderProps>;
+
+export { AutoScrollContainer, type AutoScrollContainerProps, type AutoScrollContainerRef, type DefinitionsContextValue, DefinitionsProvider, type DefinitionsProviderProps, type HtmlElementNode, Incremark, IncremarkContainerProvider, type IncremarkContainerProviderProps, IncremarkFootnotes, IncremarkHtmlElement, type IncremarkHtmlElementProps, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, ThemeProvider, type ThemeProviderProps, type TypewriterControls, type TypewriterOptions, type UseBlockTransformerOptions, type UseBlockTransformerReturn, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useBlockTransformer, useDefinitions, useDevTools, useIncremark };