mn-rails-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Temsys-Shen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,679 @@
+import * as marginnote from 'marginnote';
+import { MbModelTool, MbBookNote, MbTopic, MbBook, DictObj } from 'marginnote';
+export { DictObj, MbBook, MbBookNote, MbTopic, NoteComment } from 'marginnote';
+
+/**
+ * 笔记数据库操作类
+ * 基于 marginnote 的 MbModelTool 封装，提供 getAllNotes、createNote 等便捷 API
+ */
+
+declare class NoteDatabase {
+    private db;
+    constructor(db?: MbModelTool);
+    getNoteById(noteId: string): MbBookNote | null;
+    getNotebookById(notebookId: string): MbTopic | null;
+    getDocumentById(md5: string): MbBook | null;
+    getMediaByHash(hash: string): {
+        base64Encoding(): string;
+    } | null;
+    /**
+     * 获取所有笔记。若提供 notebookId 则返回该笔记本的笔记，否则聚合所有笔记本的笔记。
+     */
+    getAllNotes(notebookId?: string): MbBookNote[];
+    createNote(title: string, notebookId: string, docMd5?: string): MbBookNote | null;
+    updateNote(noteId: string, updates: Partial<MbBookNote>): boolean;
+    deleteNote(noteId: string): boolean;
+}
+
+declare const MN: Omit<{
+    readonly app: marginnote.Application;
+    readonly db: marginnote.MbModelTool;
+    get studyController(): marginnote.StudyController;
+    get notebookController(): marginnote.NotebookController;
+    get currentDocumentController(): marginnote.DocumentController;
+    get currentWindow(): any;
+    get currentThemeColor(): marginnote.UIColor;
+    get currentAddon(): {
+        key: string;
+        title: string;
+    };
+    get currnetNotebookId(): string | undefined;
+    get currentDocmd5(): string | undefined;
+    readonly isZH: boolean;
+    readonly version: string;
+    readonly isMNE: boolean;
+    readonly isMac: boolean;
+    readonly isMacMNE: boolean;
+    readonly isMacMN3: boolean;
+    readonly themeColor: {
+        Gray: marginnote.UIColor;
+        Default: marginnote.UIColor;
+        Dark: marginnote.UIColor;
+        Green: marginnote.UIColor;
+        Sepia: marginnote.UIColor;
+    };
+    log(obj: any, suffix?: string, ...args: any[]): void;
+    error(obj: any, suffix?: string, ...args: any[]): void;
+}, "db"> & {
+    readonly db: NoteDatabase;
+    readonly currentNotebookId: string | undefined;
+};
+
+interface LinkedNote {
+    summary: boolean;
+    noteid: string;
+    linktext: string;
+}
+interface PluginLifecycle {
+    onLaunch?(): void;
+    onExit?(): void;
+    onProfileChanged?(profileId: string): void;
+    onNotebookChanged?(notebookId: string): void;
+    onNotebookClosing?(notebookId: string): void;
+    onDocumentOpened?(docMd5: string): void;
+    onDocumentClosing?(docMd5: string): void;
+    onNoteSelected?(note: MbBookNote): void;
+}
+interface ControllerLifecycle {
+    onInit?(): void;
+    onDestroy?(): void;
+}
+type Actions = Record<string, (...args: any[]) => any>;
+interface StateDefinition {
+    [key: string]: any;
+}
+interface WebViewConfig {
+    component: string;
+    props?: marginnote.DictObj;
+}
+interface ButtonConfig {
+    title: string;
+    action: () => void;
+    style?: 'default' | 'primary' | 'danger';
+}
+
+/**
+ * 生命周期管理器
+ * 将 App 生命周期映射到 MarginNote 的 defineLifecycleHandlers（由 marginnote 提供）
+ */
+
+/**
+ * 生命周期管理器
+ * 将 App 类的生命周期方法映射到 MarginNote 的原生生命周期钩子
+ */
+declare class LifecycleManager {
+    private app;
+    constructor(app: PluginLifecycle);
+    /**
+     * 注册生命周期钩子
+     */
+    private register;
+    /**
+     * 手动触发笔记选中事件
+     *
+     * MarginNote 没有提供"笔记选中"的原生生命周期钩子，因此需要开发者手动监听 MarginNote 的笔记选择相关 API，
+     * 并在检测到笔记选中时调用此方法。
+     *
+     * 调用此方法会触发 App 的 `onNoteSelected` 钩子。
+     *
+     * 典型用法：
+     * 1. 在 App 的 `onLaunch` 中注册 MarginNote 的笔记选择监听器（如通过 `MN.notificationCenter` 或其他 API）
+     * 2. 在监听器回调中调用 `this.lifecycle.triggerNoteSelected(note)`
+     * 3. 框架会自动调用 App 的 `onNoteSelected` 方法
+     *
+     * @param note - 被选中的笔记对象
+     *
+     * @example
+     * ```typescript
+     * class MyPlugin extends App {
+     *   onLaunch() {
+     *     // 注册笔记选择监听
+     *     MN.notificationCenter.addObserver('noteSelected', (note) => {
+     *       this.lifecycle?.triggerNoteSelected(note);
+     *     });
+     *   }
+     *
+     *   onNoteSelected(note) {
+     *     console.log('Note selected:', note);
+     *   }
+     * }
+     * ```
+     */
+    triggerNoteSelected(note: MbBookNote): void;
+    /**
+     * 手动触发配置文件切换事件
+     *
+     * MarginNote 没有提供"配置文件切换"的原生生命周期钩子，因此需要开发者手动监听 MarginNote 的配置切换相关 API，
+     * 并在检测到配置切换时调用此方法。
+     *
+     * 调用此方法会触发 App 的 `onProfileChanged` 钩子。
+     *
+     * 典型用法：
+     * 1. 在 App 的 `onLaunch` 中注册 MarginNote 的配置切换监听器（如通过 `MN.notificationCenter` 或其他 API）
+     * 2. 在监听器回调中调用 `this.lifecycle.triggerProfileChanged(profileId)`
+     * 3. 框架会自动调用 App 的 `onProfileChanged` 方法
+     *
+     * @param profileId - 新的配置文件 ID
+     *
+     * @example
+     * ```typescript
+     * class MyPlugin extends App {
+     *   onLaunch() {
+     *     // 注册配置切换监听
+     *     MN.notificationCenter.addObserver('profileChanged', (profileId) => {
+     *       this.lifecycle?.triggerProfileChanged(profileId);
+     *     });
+     *   }
+     *
+     *   onProfileChanged(profileId) {
+     *     console.log('Profile changed to:', profileId);
+     *   }
+     * }
+     * ```
+     */
+    triggerProfileChanged(profileId: string): void;
+}
+
+/**
+ * App 基类
+ * 插件主入口，管理插件生命周期
+ */
+
+declare abstract class App implements PluginLifecycle {
+    private lifecycleManager?;
+    constructor();
+    /**
+     * 插件启动时调用
+     */
+    onLaunch?(): void;
+    /**
+     * 插件退出时调用
+     */
+    onExit?(): void;
+    /**
+     * 配置文件切换时调用
+     */
+    onProfileChanged?(profileId: string): void;
+    /**
+     * 笔记本切换时调用
+     */
+    onNotebookChanged?(notebookId: string): void;
+    /**
+     * 笔记本关闭时调用
+     */
+    onNotebookClosing?(notebookId: string): void;
+    /**
+     * 文档打开时调用
+     */
+    onDocumentOpened?(docMd5: string): void;
+    /**
+     * 文档关闭时调用
+     */
+    onDocumentClosing?(docMd5: string): void;
+    /**
+     * 笔记选中时调用
+     */
+    onNoteSelected?(note: any): void;
+    /**
+     * 获取生命周期管理器（用于手动触发事件）
+     *
+     * 返回 LifecycleManager 实例，用于在 App 子类中手动触发某些生命周期事件。
+     *
+     * 典型用法：
+     * - 在 `onLaunch` 中注册 MarginNote 的监听器（如笔记选择、配置切换等）
+     * - 在监听器回调中调用 `this.lifecycle.triggerNoteSelected(note)` 或 `this.lifecycle.triggerProfileChanged(profileId)`
+     * - 这些调用会触发对应的 `onNoteSelected` 或 `onProfileChanged` 钩子
+     *
+     * @example
+     * ```typescript
+     * class MyPlugin extends App {
+     *   onLaunch() {
+     *     // 注册笔记选择监听
+     *     MN.notificationCenter.addObserver('noteSelected', (note) => {
+     *       this.lifecycle?.triggerNoteSelected(note);
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    protected get lifecycle(): LifecycleManager | undefined;
+}
+
+/**
+ * Controller 基类
+ * 处理业务逻辑，定义 actions 供 Web 端调用
+ */
+
+declare abstract class Controller implements ControllerLifecycle {
+    private controllerName;
+    constructor(name?: string);
+    /**
+     * Controller 初始化时调用
+     */
+    onInit?(): void;
+    /**
+     * Controller 销毁时调用
+     */
+    onDestroy?(): void;
+    /**
+     * 定义供 Web 端调用的 actions
+     * 子类应该重写此属性以提供类型安全的 API
+     */
+    actions: Actions;
+    /**
+     * 注册 actions 到 Bridge
+     */
+    private registerActions;
+    /**
+     * 注销 actions
+     */
+    private unregisterActions;
+    /**
+     * 更新 actions（当 actions 发生变化时调用）
+     */
+    protected updateActions(): void;
+}
+
+/**
+ * 配置管理类
+ * 用于读取和持久化插件配置（基于 NSUserDefaults，类型由 marginnote 提供）
+ */
+/**
+ * 配置管理器
+ */
+declare class Config {
+    private prefix;
+    constructor(prefix: string);
+    get<T = any>(key: string, defaultValue?: T): T | undefined;
+    set<T = any>(key: string, value: T): boolean;
+    remove(key: string): boolean;
+    getAll(): Record<string, any>;
+    clear(): boolean;
+}
+
+/**
+ * 状态管理器
+ * 实现响应式状态管理，支持原生和 Web 端状态同步
+ */
+
+type StateChangeListener<T = any> = (newValue: T, oldValue: T, key: string) => void;
+interface StateOptions {
+    deep?: boolean;
+    immediate?: boolean;
+}
+/**
+ * 状态管理器类
+ */
+declare class StateManager<T extends DictObj = DictObj> {
+    private state;
+    private watchHandles;
+    private webViewWatchHandles;
+    private registeredWebViews;
+    private autoSyncHandle;
+    private isSyncing;
+    constructor(initialState: T);
+    /**
+     * 获取状态值
+     */
+    get<K extends keyof T>(key: K): T[K];
+    /**
+     * 设置状态值
+     */
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    /**
+     * 获取整个状态对象
+     */
+    getState(): T;
+    /**
+     * 监听状态变化
+     */
+    watch<K extends keyof T>(key: K, listener: StateChangeListener<T[K]>, options?: StateOptions): () => void;
+    /**
+     * 监听整个状态变化
+     */
+    watchAll(listener: (state: T) => void): () => void;
+    /**
+     * 同步状态到 WebView
+     */
+    syncToWebView(webViewId: string, state?: T): void;
+    /**
+     * 从 WebView 同步状态
+     */
+    syncFromWebView(webViewId: string, state: Partial<T>): void;
+    /**
+     * 注册需要同步状态的 WebView
+     */
+    registerWebView(webViewId: string): void;
+    /**
+     * 取消注册 WebView
+     */
+    unregisterWebView(webViewId: string): void;
+    /**
+     * 同步初始状态到新注册的 WebView
+     */
+    syncInitialState(webViewId: string): void;
+    /**
+     * 设置自动同步监听
+     */
+    private setupAutoSync;
+    /**
+     * 清理资源
+     */
+    destroy(): void;
+}
+/**
+ * 定义状态
+ */
+declare function defineState<T extends DictObj>(name: string, initialState: T): StateManager<T>;
+/**
+ * 获取状态管理器
+ */
+declare function getState<T extends DictObj>(name: string): StateManager<T> | undefined;
+
+/**
+ * Bridge 对象
+ * 用于在 WebView 中类型安全地调用 Controller 的 actions
+ */
+
+/**
+ * Bridge 消息类型
+ */
+interface BridgeMessage {
+    id: string;
+    controller: string;
+    action: string;
+    args: any[];
+}
+interface BridgeResponse {
+    id: string;
+    success: boolean;
+    data?: any;
+    error?: string;
+}
+/**
+ * Bridge 管理器
+ * 管理所有 Controller 的 actions，并提供类型安全的调用接口
+ */
+declare class BridgeManager {
+    private controllers;
+    private pendingRequests;
+    /**
+     * 注册 Controller 的 actions
+     */
+    register(controllerName: string, actions: Actions): void;
+    /**
+     * 注销 Controller
+     */
+    unregister(controllerName: string): void;
+    /**
+     * 调用 action
+     */
+    call(controllerName: string, actionName: string, ...args: any[]): Promise<any>;
+    /**
+     * 处理来自 WebView 的消息
+     */
+    handleMessage(message: BridgeMessage): Promise<BridgeResponse>;
+    /**
+     * 获取所有已注册的 Controller 名称
+     */
+    getControllerNames(): string[];
+    /**
+     * 获取 Controller 的所有 action 名称
+     */
+    getActionNames(controllerName: string): string[];
+}
+/**
+ * 获取 Bridge 管理器实例
+ */
+declare function getBridgeManager(): BridgeManager;
+/**
+ * Bridge 对象（用于 WebView）
+ * 这个对象会被注入到 WebView 中，提供类型安全的 API 调用
+ */
+declare const bridge: Record<string, Record<string, (...args: any[]) => Promise<any>>>;
+
+/**
+ * 消息桥接
+ * 处理原生与 WebView 之间的双向通信
+ */
+
+/**
+ * 消息桥接管理器
+ */
+declare class MessageBridge {
+    private webViews;
+    /**
+     * 注册 WebView
+     */
+    registerWebView(webViewId: string, webView: any): void;
+    /**
+     * 注销 WebView
+     */
+    unregisterWebView(webViewId: string): void;
+    /**
+     * 注入 bridge 脚本到 WebView
+     */
+    private injectBridgeScript;
+    /**
+     * 处理来自 WebView 的消息
+     */
+    handleWebViewMessage(webViewId: string, message: BridgeMessage): Promise<BridgeResponse>;
+    /**
+     * 发送消息到 WebView
+     */
+    sendToWebView(webViewId: string, type: string, payload: any): void;
+}
+/**
+ * 获取消息桥接实例
+ */
+declare function getMessageBridge(): MessageBridge;
+
+/**
+ * Web 端 Bridge 类型定义
+ * 用于在 WebView 中提供类型安全的 bridge 对象
+ */
+/**
+ * Web 端 Bridge 接口
+ * 这个接口会被注入到 WebView 中
+ */
+interface WebBridge {
+    [controllerName: string]: {
+        [actionName: string]: (...args: any[]) => Promise<any>;
+    };
+}
+declare function createWebBridge(): WebBridge;
+
+/**
+ * WebView 管理器
+ * 负责创建、管理和渲染 WebView（UIKit 类型由 marginnote 提供）
+ */
+
+interface WebViewInstance {
+    id: string;
+    webView: any;
+    component: string;
+    props?: DictObj;
+}
+/**
+ * WebView 管理器类
+ */
+declare class WebViewManager {
+    private webViews;
+    private messageBridge;
+    private componentCache;
+    /**
+     * 渲染 WebView
+     */
+    render(component: string, props?: DictObj, frame?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<WebViewInstance | null>;
+    /**
+     * 加载组件文件
+     * 只允许加载编译后的文件（.js）或 HTML 文件（最终产物）
+     * 禁止运行时解析 .vue 或 .jsx 源文件
+     */
+    private loadComponent;
+    /**
+     * 解析组件内容
+     * 只支持 HTML 和 JS 文件（最终产物）
+     * 禁止运行时解析 .vue 或 .jsx 源文件
+     */
+    private parseComponentContent;
+    /**
+     * 加载类型定义文件
+     */
+    private loadTypeDefinitions;
+    /**
+     * 生成 HTML 内容
+     */
+    private generateHTML;
+    /**
+     * 销毁 WebView
+     */
+    destroy(webViewId: string): boolean;
+    /**
+     * 获取 WebView 实例
+     */
+    get(webViewId: string): WebViewInstance | undefined;
+    /**
+     * 获取所有 WebView 实例
+     */
+    getAll(): WebViewInstance[];
+    /**
+     * 更新 WebView 的 props
+     */
+    updateProps(webViewId: string, props: DictObj): boolean;
+}
+/**
+ * 获取 WebView 管理器实例
+ */
+declare function getWebViewManager(): WebViewManager;
+
+/**
+ * 原生 UI 管理器
+ * 负责创建和管理原生 UI 元素（UIKit 类型由 marginnote 提供）
+ */
+
+interface UIElement {
+    id: string;
+    element: any;
+    type: 'button' | 'label' | 'view';
+}
+declare class NativeUIManager {
+    private elements;
+    createButton(config: ButtonConfig & {
+        frame?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): UIElement | null;
+    createLabel(config: {
+        text: string;
+        frame?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        color?: any;
+    }): UIElement | null;
+    private getColorForStyle;
+    destroy(elementId: string): boolean;
+    get(elementId: string): UIElement | undefined;
+    getAll(): UIElement[];
+    clear(): void;
+}
+declare function getNativeUIManager(): NativeUIManager;
+
+/**
+ * 对话框工具函数
+ * 基于 marginnote 的 UIAlertView、UIAlertViewStyle 等（由 marginnote 提供）
+ */
+/**
+ * 显示警告消息（不可交互）
+ */
+declare function alert(message: string): void;
+/**
+ * 弹出对话框
+ */
+interface PopupOptions {
+    title?: string;
+    message: string;
+    type?: number;
+    buttons?: string[];
+    canCancel?: boolean;
+    multiLine?: boolean;
+}
+interface PopupResult {
+    inputContent?: string;
+    buttonIndex: number;
+}
+declare function popup(options: PopupOptions): Promise<PopupResult>;
+/**
+ * 确认对话框
+ */
+declare function confirm(title?: string, message?: string): Promise<boolean>;
+/**
+ * 选择对话框
+ */
+interface SelectResult {
+    value: string;
+    index: number;
+}
+declare function select(options: string[], title?: string, message?: string, canCancel?: boolean): Promise<SelectResult | null>;
+
+/**
+ * 文件操作工具函数（NSFileManager 等由 marginnote 提供）
+ */
+/**
+ * 读取文件内容
+ */
+declare function readFile(path: string): string | null;
+/**
+ * 检查文件是否存在
+ */
+declare function fileExists(path: string): boolean;
+/**
+ * 创建目录
+ */
+declare function createDirectory(path: string, createIntermediates?: boolean): boolean;
+/**
+ * 获取插件目录路径
+ */
+declare function getAddonPath(): string | null;
+/**
+ * 获取组件视图目录路径
+ */
+declare function getViewsPath(): string | null;
+
+/**
+ * 笔记操作工具函数
+ */
+
+/**
+ * 获取笔记的所有文本内容（包括摘录和评论）
+ */
+declare function getNoteAllText(note: MbBookNote): string;
+/**
+ * 检查笔记是否存在
+ */
+declare function isNoteExist(note: MbBookNote | string): boolean;
+/**
+ * 获取笔记的链接笔记
+ */
+declare function getLinkedNotes(note: MbBookNote): MbBookNote[];
+/**
+ * 获取笔记的子笔记
+ */
+declare function getChildNotes(note: MbBookNote): MbBookNote[];
+/**
+ * 获取笔记的父笔记
+ */
+declare function getParentNote(note: MbBookNote): MbBookNote | null;
+
+export { type Actions, App, BridgeManager, type ButtonConfig, Config, Controller, type ControllerLifecycle, LifecycleManager, type LinkedNote, MN, MessageBridge, NativeUIManager, NoteDatabase, type PluginLifecycle, type StateDefinition, StateManager, type WebBridge, type WebViewConfig, WebViewManager, alert, bridge, confirm, createDirectory, createWebBridge, defineState, fileExists, getAddonPath, getBridgeManager, getChildNotes, getLinkedNotes, getMessageBridge, getNativeUIManager, getNoteAllText, getParentNote, getState, getViewsPath, getWebViewManager, isNoteExist, popup, readFile, select };