@virid/main 0.1.0 → 0.1.1

package/README.md

@@ -1 +1,160 @@
-todo
+# @virid/main
+
+**@virid/main** is the main process adapter for Electron applications. It provides automatic routing for `ToRendererMessage` and `FromRendererMessage`, along with the capability to receive and manage reporting from rendering processes.
+
+## 🌟 Core Design Philosophy
+
+In **@virid/main**, messages sent from the main process to a rendering process are abstracted as `ToRendererMessage`. These messages can be distributed directly via the dispatcher, traveling through IPC to the target rendering process to trigger the corresponding **System**.
+
+Conversely, messages sent from a rendering process to the main process are abstracted as `FromRendererMessage`. Once a rendering process sends a message, the `FromRendererMessage` is automatically delivered to the dispatcher to trigger the relevant main process **System**.
+
+- **Automatic Route Registration**: When a rendering process window opens, it automatically registers itself with the main process. All subsequent messages will carry the window's specific metadata (context).
+- **Type Restoration**: After passing through the IPC channel, messages are restored into their original **Message** classes before re-entering `@virid/core`. This allows them to be recognized and distributed by the dispatcher, achieving **location transparency** across different processes.
+- **Targeted Messaging & Broadcasting**: You can achieve point-to-point communication by using the specific IDs of rendering processes, or use `*` to broadcast messages to all windows.
+
+## 🔌Enable plugins
+
+```ts
+import { createVirid } from '@virid/core'
+import { MainPlugin } from '@virid/main'
+import { app } from 'electron'
+const virid = createVirid()
+  .use(MainPlugin, { electronApp: app })
+```
+
+## 🛠️ @virid/main Core API Overview
+
+### ToRendererMessage
+
+- **Function**: A specialized message base class designed for inheritance. All messages inheriting from `ToRendererMessage` will be dispatched to the rendering process.
+- **Logic**: This message type requires two specific metadata tags:
+  - `__virid_target`: Specifies the destination (e.g., a specific `windowId`).
+  - `__virid_messageType`: Defines the message type it should be restored to upon reaching the rendering process.
+
+- Example:
+
+**In the Main Process:**
+
+```ts
+import { ToRendererMessage } from '@virid/main'
+
+/**
+ * - __virid_target = 'renderer': Indicates the message is bound for the rendering process 
+ * with the windowId 'renderer'.
+ * - __virid_messageType = 'file-dialog': Describes the type this message will transform 
+ * into once it arrives in the rendering process.
+ */
+export class RenderDialogMessage extends ToRendererMessage {
+  __virid_target: string = 'renderer'
+  __virid_messageType: string = 'file-dialog'
+  
+  constructor(public path: string) {
+    super()
+  }
+}
+```
+
+In the **Rendering Process**, you can use the `@FromIpc` decorator in conjunction with `FromMainMessage` to handle the conversion. For more details, refer to `@virid/renderer`.
+
+**In the Rendering Process:**
+
+```ts
+import { FromIpc, FromMainMessage } from '@virid/renderer'
+
+/**
+ * @FromIpc('file-dialog') indicates that when the Main Process sends a ToRendererMessage 
+ * where __virid_messageType is 'file-dialog', this message will be automatically 
+ * delivered to the Virid dispatcher to trigger the corresponding rendering process System.
+ */
+@FromIpc('file-dialog')
+class ChooseBgImageMessage extends FromMainMessage {
+  constructor(public path: string) {
+    super()
+  }
+}
+```
+
+### FromRenderMessage / @FromRenderer()
+
+- **Function**: A specialized message base class designed for inheritance. All messages inheriting from `FromRenderMessage` will be automatically converted and dispatched to the **Virid Dispatcher** in the Main Process when sent from a Rendering Process.
+- **Logic**: The `@FromRenderer()` decorator accepts a string-based ID. This ID must match the `__virid_messageType` of the `ToMainMessage` dispatched from the Rendering Process.
+
+#### Example:
+
+**In the Main Process:**
+
+```ts
+import { FromRenderer, FromRenderMessage, ToRendererMessage } from '@virid/main'
+
+// Message to be sent to the Rendering Process
+export class RenderDialogMessage extends ToRendererMessage {
+  __virid_target: string = 'renderer'
+  __virid_messageType: string = 'file-dialog'
+  constructor(public path: string) {
+    super()
+  }
+}
+
+/**
+ * Converts incoming messages from the Rendering Process with 
+ * __virid_messageType: 'open-dialog' into the Main Process's OpenDialogMessage.
+ */
+@FromRenderer('open-dialog')
+export class OpenDialogMessage extends FromRenderMessage {
+  constructor(
+    public options: {
+      title?: string
+      filters?: Array<{ name: string; extensions: string[] }>
+      properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>
+    }
+  ) {
+    super()
+  }
+}
+
+export class WindowSystem {
+  @System()
+  async openDialog(@Message(OpenDialogMessage) message: OpenDialogMessage) {
+    // Invoke native Electron dialog
+    const result = await dialog.showOpenDialog(message.senderWindow, message.options)
+    
+    // If the user did not cancel and selected a file
+    if (!result.canceled && result.filePaths.length > 0) {
+      const selectedPath = result.filePaths[0]
+      return new RenderDialogMessage(selectedPath)
+    }
+    return
+  }
+}
+```
+
+In the **Rendering Process**, you can use `@FromIpc` in conjunction with `ToMainMessage` to handle message conversion and dispatching. For more details, refer to `@virid/renderer`.
+
+**In the Rendering Process:**
+
+```ts
+import { ToMainMessage, FromIpc, FromMainMessage } from '@virid/renderer'
+
+// Handles the incoming file selection result
+@FromIpc('file-dialog')
+class ChooseBgImageMessage extends FromMainMessage {
+  constructor(public path: string) {
+    super()
+  }
+}
+
+// Initiates the request to open a dialog
+class OpenDialogMessage extends ToMainMessage {
+  __virid_target: string = 'main'
+  __virid_messageType: string = 'open-dialog'
+  constructor(
+    public options: {
+      title?: string
+      filters?: Array<{ name: string; extensions: string[] }>
+      properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>
+    }
+  ) {
+    super()
+  }
+}
+```

package/README.zh.md

@@ -1 +1,138 @@
-todo
+#  @virid/main
+
+`@virid/main` 是electron应用的主适配器，提供`ToRendererMessage`和`FromRendererMessage`的自动路由功能与接受渲染进程报道功能。
+
+## 🌟 核心设计理念
+
+在 `@virid/main` 中，主进程朝渲染进程发送消息被抽象为`ToRendererMessage`，该消息可以直接通过调度器分发，消息将会通过IPC直接传送到渲染进程并触发对应的`System`。渲染进程朝主进程发送的消息被抽象为`FromRendererMessage`，一旦渲染进程发送了对应的消息，`FromRendererMessage`将会自动被投递到调度器触发相应的主进程`System`。
+
+- **路由自动注册**：渲染进程窗口开启后，自动向主进程注册自身，以后所有的消息都将携带自身的窗口信息。
+- **类型恢复**：消息在通过IPC通道后，恢复成真正的Message类重新进入`@virid/core`并被调度器识别并分发。实现不同进程的位置无关性。
+- **消息定向与广播**：可以通过其他渲染进程的ID来实现定向通信，或者使用“*”来广播消息。
+
+## 🔌启用插件
+
+```ts
+import { createVirid } from '@virid/core'
+import { MainPlugin } from '@virid/main'
+import { app } from 'electron'
+const virid = createVirid()
+  .use(MainPlugin, { electronApp: app })
+```
+
+## 🛠️ @virid/main 核心 API 概览
+
+### `ToRendererMessage`
+
+- **功能**：一个特殊的消息基类，可被继承。所有继承自`ToRendererMessage`的Message将被发往渲染进程
+- **逻辑**：该消息类型需要两个特殊标记，`__virid_target`标记了目的地，`__virid_messageType`标记了在目的地应该被还原为的Message类型
+- **示例**：
+
+```ts
+//在主进程
+import { ToRendererMessage } from '@virid/main'
+// __virid_target=‘renderer’,说明消息需要发往windowId为renderer的渲染进程
+//  __virid_messageType: string = 'file-dialog'，描述了在渲染进程，该消息将会重新变为的类型
+export class RenderDialogMessage extends ToRendererMessage {
+  __virid_target: string = 'renderer'
+  __virid_messageType: string = 'file-dialog'
+  constructor(public path: string) {
+    super()
+  }
+}
+```
+
+在渲染进程，可以通过`@FromIpc`结合`FromMainMessage`来实现对应的转换。详情见`@virid/renderer` 。
+
+```ts
+//在渲染进程
+import { FromIpc, FromMainMessage } from '@virid/main'
+//@FromIpc('file-dialog')表明当主进程发送一个ToRenderMessage，而且
+//  __virid_target: string = 'renderer'
+//  __virid_messageType: string = 'file-dialog'
+// 时，这个消息将被自动投递到virid调度中心触发相应的渲染进程System
+@FromIpc('file-dialog')
+class ChooseBgImageMessage extends FromMainMessage {
+  constructor(public path: string) {
+    super()
+  }
+}
+```
+
+### `FromRenderMessage/@FromRenderer()`
+
+- **功能**：一个特殊的消息基类，可被继承。所有继承自`FromRenderMessage`的Message将在渲染进程发送消息时自动转换并投递到主进程的`virid`调度中心
+- **逻辑**：`@FromRenderer()`接受一个字符串类型的ID，该ID与渲染进程中发送的`ToMainMessage`的ID应该相同。
+- **示例**：
+
+```ts
+//在主进程
+import { FromRenderer, FromRenderMessage } from '@virid/renderer'
+// 发往渲染进程的消息
+export class RenderDialogMessage extends ToRendererMessage {
+  __virid_target: string = 'renderer'
+  __virid_messageType: string = 'file-dialog'
+  constructor(public path: string) {
+    super()
+  }
+}
+// 将来自渲染进程且 __virid_messageType: string = 'file-dialog'的消息转换成主进程的OpenDialogMessage
+@FromRenderer('open-dialog')
+export class OpenDialogMessage extends FromRenderMessage {
+  constructor(
+    public options: {
+      title?: string
+      filters?: Array<{ name: string; extensions: string[] }>
+      properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>
+    }
+  ) {
+    super()
+  }
+}
+
+export class WindowSystem {
+  @System()
+  async openDialog(@Message(OpenDialogMessage) message: OpenDialogMessage) {
+    // 调用原生对话框
+    const result = await dialog.showOpenDialog(message.senderWindow, message.options)
+    // 如果用户没有取消，并且确实选择了文件
+    if (!result.canceled && result.filePaths.length > 0) {
+      const selectedPath = result.filePaths[0]
+      return new RenderDialogMessage(selectedPath)
+    }
+    return
+  }
+}
+```
+
+在渲染进程，可以通过`@FromIpc`结合`ToMainMessage`来实现对应的转换和消息的发送。详情见`@virid/renderer` 。
+
+```ts
+// 在渲染进程
+import { ToMainMessage，FromIpc } from '@virid/renderer'
+// 打开文件选择框
+@FromIpc('file-dialog')
+class ChooseBgImageMessage extends FromMainMessage {
+  constructor(public path: string) {
+    super()
+  }
+}
+//打开文件选择框
+class OpenDialogMessage extends ToMainMessage {
+  __virid_target: string = 'main'
+  __virid_messageType: string = 'open-dialog'
+  constructor(
+    public options: {
+      title?: string
+      filters?: Array<{ name: string; extensions: string[] }>
+      properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>
+    }
+  ) {
+    super()
+  }
+}
+
+```
+
+
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@virid/main",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Electron main process adapter for Virid, responsible for sending, receiving, and broadcasting rendering process messages",
   "author": "Ailrid",
   "license": "Apache 2.0",
@@ -13,7 +13,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ArisuYuki/virid.git"
+    "url": "git+https://github.com/Ailrid/virid.git"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -35,7 +35,7 @@
   "dependencies": {},
   "peerDependencies": {
     "electron": "^30.0.0",
-    "@virid/core": "0.1.0"
+    "@virid/core": "0.1.1"
   },
   "scripts": {
     "build": "tsup --config tsup.config.ts",