@huanban/rulego-editor-react 1.0.15 → 1.1.0

package/dist/hooks/useEditorCore.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @file hooks/useEditorCore.ts
+ * @description React Hook — 将 EditorCore 桥接到 React 状态系统
+ *
+ * 兼容性:
+ * - React 16.8+ (hooks 引入版本)
+ * - React 17.x
+ * - React 18.x / 19.x
+ * - Next.js Pages Router 和 App Router
+ *
+ * 设计决策:
+ * - 使用 useEffect + useState 而非 React 18 的 useSyncExternalStore,
+ *   以确保对 React 16.8+ 的兼容性
+ * - 对于 Next.js SSR, EditorCore 实例仅在 useEffect 中创建 (客户端)
+ *
+ * 使用方式:
+ * ```tsx
+ * import { useEditorCore } from '@huanban/rulego-editor-react'
+ *
+ * function MyEditor() {
+ *   const {
+ *     core,
+ *     isReady,
+ *     isDirty,
+ *     selectedNode,
+ *     componentGroups,
+ *     on,
+ *     loadData,
+ *   } = useEditorCore({ url: 'http://127.0.0.1:9090' })  // 通过 url 参数传入实际地址
+ *
+ *   return <div ref={canvasRef} />
+ * }
+ * ```
+ *
+ * Next.js 兼容用法:
+ * ```tsx
+ * // 在 Next.js 中, 使用动态导入避免 SSR 报错
+ * import dynamic from 'next/dynamic'
+ * const Editor = dynamic(() => import('./Editor'), { ssr: false })
+ * ```
+ *
+ * @see EditorCore — 编辑器核心引擎
+ */
+import { EditorCore } from '@huanban/rulego-editor-core';
+import type { EditorOptions, EditorEventMap, EditorEventName, RuleChainData, RuleNodeConfig, RuleConnectionConfig, ComponentDefinition, ComponentGroup } from '@huanban/rulego-editor-core';
+/**
+ * Hook 内部管理的状态
+ */
+interface EditorState {
+    /** 编辑器是否就绪 */
+    isReady: boolean;
+    /** 数据是否已修改 */
+    isDirty: boolean;
+    /** 是否正在加载 */
+    isLoading: boolean;
+    /** 当前选中的节点 */
+    selectedNode: RuleNodeConfig | null;
+    /** 当前选中的边 */
+    selectedEdge: RuleConnectionConfig | null;
+    /** 组件分组 */
+    componentGroups: ComponentGroup[];
+    /** 当前编辑的节点视图 */
+    currentNodeView: ComponentDefinition | null;
+    /** 当前编辑的节点模型 */
+    currentNodeModel: Record<string, unknown>;
+    /** 当前编辑的边模型 */
+    currentEdgeModel: Record<string, unknown>;
+    /** 是否可撤销 */
+    canUndo: boolean;
+    /** 是否可重做 */
+    canRedo: boolean;
+}
+/**
+ * useEditorCore 返回的 Hook 接口
+ */
+export interface UseEditorCoreReturn extends EditorState {
+    /** EditorCore 原始实例 */
+    core: EditorCore | null;
+    /** 加载规则链数据 */
+    loadData: (data: RuleChainData) => void;
+    /** 监听事件 (在组件卸载时自动清理) */
+    on: <E extends EditorEventName>(event: E, handler: (payload: EditorEventMap[E]) => void) => void;
+    /** 发送事件 */
+    emit: <E extends EditorEventName>(event: E, ...args: EditorEventMap[E] extends void ? [] : [EditorEventMap[E]]) => void;
+    /** 初始化 (传入 LogicFlow 实例) */
+    init: (lfInstance: unknown) => void;
+    /** 手动触发保存 */
+    save: () => void;
+}
+/**
+ * React Hook — 创建和管理 EditorCore
+ *
+ * @param options - 编辑器选项 (仅在首次渲染时使用)
+ * @returns 编辑器状态和操作方法
+ *
+ * 内部原理:
+ * - 使用 useRef 持有 EditorCore 实例 (避免重复创建)
+ * - 使用 useState 维护状态 (确保 React 重渲染)
+ * - 使用 useEffect 进行状态订阅和清理
+ * - 避免使用 React 18 专有 API, 确保 16.8+ 兼容性
+ */
+export declare function useEditorCore(options?: Partial<EditorOptions>): UseEditorCoreReturn;
+export {};
+//# sourceMappingURL=useEditorCore.d.ts.map

package/dist/hooks/useEditorI18n.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file hooks/useEditorI18n.ts
+ * @description React Hook — 国际化
+ *
+ * 兼容 React 16.8+, 不使用 React 18 专有 API。
+ *
+ * 使用方式:
+ * ```tsx
+ * const { t, locale, setLocale } = useEditorI18n(core)
+ *
+ * return <button>{t('toolbar.save')}</button>
+ * ```
+ */
+import type { EditorCore } from '@huanban/rulego-editor-core';
+/**
+ * useEditorI18n 返回类型
+ */
+export interface UseEditorI18nReturn {
+    /** 翻译函数 */
+    t: (key: string, params?: Record<string, string>) => string;
+    /** 当前语言 */
+    locale: string;
+    /** 切换语言 */
+    setLocale: (locale: string) => void;
+}
+/**
+ * 国际化 Hook
+ *
+ * @param core - EditorCore 实例 (可空, SSR 安全)
+ * @returns 翻译函数和语言操作
+ */
+export declare function useEditorI18n(core: EditorCore | null): UseEditorI18nReturn;
+//# sourceMappingURL=useEditorI18n.d.ts.map

package/dist/hooks/useEditorTheme.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file hooks/useEditorTheme.ts
+ * @description React Hook — 主题管理
+ *
+ * 兼容 React 16.8+, 不使用 React 18 专有 API。
+ *
+ * 使用方式:
+ * ```tsx
+ * const { currentTheme, setTheme, themes } = useEditorTheme(core)
+ *
+ * return (
+ *   <select value={currentTheme} onChange={e => setTheme(e.target.value)}>
+ *     {themes.map(t => <option key={t}>{t}</option>)}
+ *   </select>
+ * )
+ * ```
+ */
+import type { EditorCore } from '@huanban/rulego-editor-core';
+/**
+ * useEditorTheme 返回类型
+ */
+export interface UseEditorThemeReturn {
+    /** 当前主题名称 */
+    currentTheme: string;
+    /** 可用主题列表 */
+    themes: string[];
+    /** 切换主题 */
+    setTheme: (name: string) => void;
+}
+/**
+ * 主题管理 Hook
+ *
+ * @param core - EditorCore 实例 (可空, SSR 安全)
+ * @returns 主题状态和操作
+ */
+export declare function useEditorTheme(core: EditorCore | null): UseEditorThemeReturn;
+//# sourceMappingURL=useEditorTheme.d.ts.map

package/dist/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,73 @@
+/** 快捷键配置 */
+export interface ShortcutConfig {
+    /** 按键（小写，如 's', 'z', 'delete', 'backspace'） */
+    key: string;
+    /** 是否需要 Ctrl/Cmd（自动适配 Mac） */
+    ctrl?: boolean;
+    /** 是否需要 Shift */
+    shift?: boolean;
+    /** 是否需要 Alt/Option */
+    alt?: boolean;
+    /** 是否在 input/textarea 焦点时也生效（默认 false） */
+    enableInInput?: boolean;
+    /** 描述文本（用于帮助界面） */
+    description?: string;
+    /** 处理函数 */
+    handler: (e: KeyboardEvent) => void;
+}
+/** useKeyboardShortcuts 配置 */
+export interface UseKeyboardShortcutsOptions {
+    /** 快捷键列表 */
+    shortcuts: ShortcutConfig[];
+    /** 是否启用（默认 true） */
+    enabled?: boolean;
+    /** 事件目标元素（默认 document） */
+    target?: HTMLElement | null;
+}
+/**
+ * useKeyboardShortcuts — 键盘快捷键 Hook
+ *
+ * 自动处理 Mac/Windows 快捷键差异，支持组合键。
+ *
+ * @param options - 快捷键配置
+ *
+ * @example
+ * ```tsx
+ * useKeyboardShortcuts({
+ *   shortcuts: [
+ *     { key: 's', ctrl: true, description: '保存', handler: () => save() },
+ *     { key: 'z', ctrl: true, description: '撤销', handler: () => undo() },
+ *     { key: 'z', ctrl: true, shift: true, description: '重做', handler: () => redo() },
+ *     { key: 'delete', description: '删除', handler: () => deleteSelected() },
+ *   ],
+ * })
+ * ```
+ */
+export declare function useKeyboardShortcuts(options: UseKeyboardShortcutsOptions): void;
+/**
+ * 获取快捷键显示文本
+ *
+ * @param config - 快捷键配置
+ * @returns 可读的快捷键文本（如 "⌘S" 或 "Ctrl+S"）
+ */
+export declare function getShortcutLabel(config: ShortcutConfig): string;
+/**
+ * 生成编辑器默认快捷键
+ *
+ * @param handlers - 操作回调
+ * @returns 快捷键配置列表
+ */
+export declare function getDefaultEditorShortcuts(handlers: {
+    onSave?: () => void;
+    onUndo?: () => void;
+    onRedo?: () => void;
+    onDelete?: () => void;
+    onCopy?: () => void;
+    onPaste?: () => void;
+    onSelectAll?: () => void;
+    onFitView?: () => void;
+    onZoomIn?: () => void;
+    onZoomOut?: () => void;
+    onEscape?: () => void;
+}): ShortcutConfig[];
+//# sourceMappingURL=useKeyboardShortcuts.d.ts.map