@virid/renderer 0.1.0 → 0.1.1

package/README.md

@@ -1 +1,199 @@
-todo
+# @virid/renderer
+
+**@virid/renderer** is a rendering process adapter for Electron applications. It provides automatic routing for `ToMainMessage` and `FromMainMessage`, along with main process reporting capabilities.
+
+## 🌟 Core Design Philosophy
+
+In **@virid/renderer**, messages sent from the rendering process to the main process are abstracted as `ToMainMessage`. These messages can be distributed directly via the dispatcher, traveling through IPC to the main process or other rendering processes to trigger the corresponding **System**.
+
+Conversely, messages sent from the main process to the rendering process are abstracted as `FromMainMessage`. Once the main process sends a message, it is automatically delivered to the dispatcher to trigger the relevant rendering 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.
+- **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 using the IDs of other rendering processes, or use `*` to broadcast messages.
+
+------
+
+## 🔌Enable plugins
+
+```ts
+import { createVirid } from '@virid/core'
+import { RenderPlugin } from '@virid/renderer'
+const app = createVirid()
+//Each window needs to be assigned a unique windowId to report to the main process
+app.use(RenderPlugin, {
+  windowId: 'renderer'
+})
+```
+
+## 🛠️ @virid/renderer Core API Overview
+
+### ToMainMessage
+
+- **Function**: A specialized message base class designed for inheritance. All messages inheriting from `ToMainMessage` will be dispatched to other processes.
+- **Logic**: This message type requires two specific metadata tags:
+  - `__virid_target`: Defines the destination.
+  - `__virid_messageType`: Defines the message type it should be restored to upon reaching the destination.
+- Example
+
+**In the Rendering Process:**
+
+```ts
+import { ToMainMessage } from '@virid/renderer'
+
+/**
+ * - __virid_target = 'main': Indicates the message is bound for the Main Process.
+ * - If __virid_target = '*': The message will be broadcast to all rendering processes.
+ * - __virid_messageType: Describes the class type the message will transform back into 
+ * once it arrives at the Main Process.
+ */
+
+export class CloseWindowMessage extends ToMainMessage {
+  __virid_target = 'main'
+  __virid_messageType: string = 'close-window'
+}
+
+export class MinimizeWindowMessage extends ToMainMessage {
+  __virid_target = 'main'
+  __virid_messageType: string = 'minimize-window'
+}
+
+export class MaximizeWindowMessage extends ToMainMessage {
+  __virid_target = 'main'
+  __virid_messageType: string = 'maximize-window'
+}
+```
+
+In the **Main Process**, you can use the `@FromRenderer` decorator in conjunction with `FromRendererMessage` to handle the conversion. For more details, refer to `@virid/main`.
+
+**In the Main Process:**
+
+```ts
+import { FromRendererMessage, FromRenderer } from '@virid/main'
+
+// Each ID here maps to the __virid_messageType defined in the rendering process
+@FromRenderer('close-window')
+export class CloseWindowMessage extends FromRendererMessage {}
+
+@FromRenderer('minimize-window')
+export class MinimizeWindowMessage extends FromRendererMessage {}
+
+@FromRenderer('maximize-window')
+export class MaximizeWindowMessage extends FromRendererMessage {}
+
+/**
+ * WindowSystem: Implements Minimize, Maximize, and Close functionality for all windows.
+ * senderWindow: Refers to the specific window instance that dispatched the message.
+ */
+export class WindowSystem {
+  @System()
+  closeWindow(@Message(CloseWindowMessage) message: CloseWindowMessage) {
+    message.senderWindow.close()
+  }
+
+  @System()
+  minimizeWindow(@Message(MinimizeWindowMessage) message: MinimizeWindowMessage) {
+    message.senderWindow.minimize()
+  }
+
+  @System()
+  maximizeWindow(@Message(MaximizeWindowMessage) message: MaximizeWindowMessage) {
+    if (message.senderWindow.isMaximized()) {
+      message.senderWindow.unmaximize()
+    } else {
+      message.senderWindow.maximize()
+    }
+  }
+}
+```
+
+### FromMainMessage / @FromIpc()
+
+- **Function**: A specialized message base class for inheritance. Any message inheriting from `FromMainMessage` is automatically converted and dispatched to the current process's **Virid Dispatcher** when sent from the Main Process.
+- **Logic**: The `@FromIpc()` decorator accepts a string-based ID. This ID must match the `__virid_messageType` of the `ToRendererMessage` sent from the Main Process.
+
+- Example:
+
+**In the Rendering Process:**
+
+```ts
+import { FromIpc, FromMainMessage, ToMainMessage } from '@virid/renderer'
+
+// This class handles the incoming file path from the Main Process
+@FromIpc('file-dialog')
+class ChooseBgImageMessage extends FromMainMessage {
+  constructor(public path: string) {
+    super()
+  }
+}
+
+// This class initiates the request to the Main Process
+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()
+  }
+}
+```
+
+In the **Main Process**, you use `@FromRenderer` and `FromRendererMessage` to handle the incoming request. For more details, refer to `@virid/main`.
+
+**In the Main Process:**
+
+```ts
+import { FromRendererMessage, FromRenderer, ToRendererMessage } from '@virid/main'
+
+/**
+ * @FromRenderer('open-dialog') ensures that when the Rendering Process 
+ * dispatches an OpenDialogMessage, the Main Process's corresponding 
+ * System will be triggered automatically.
+ */
+@FromRenderer('open-dialog')
+export class OpenDialogMessage extends FromRendererMessage {
+  constructor(
+    public options: {
+      title?: string
+      filters?: Array<{ name: string; extensions: string[] }>
+      properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>
+    }
+  ) {
+    super()
+  }
+}
+
+/**
+ * RenderDialogMessage is used to send the result back.
+ * - __virid_target = 'renderer' routes it back to the UI.
+ * - __virid_messageType = 'file-dialog' maps it to ChooseBgImageMessage in the renderer.
+ */
+export class RenderDialogMessage extends ToRendererMessage {
+  __virid_target: string = 'renderer'
+  __virid_messageType: string = 'file-dialog'
+  constructor(public path: string) {
+    super()
+  }
+}
+
+export class WindowSystem {
+  @System()
+  async openDialog(@Message(OpenDialogMessage) message: OpenDialogMessage) {
+    // Invoke the native Electron dialog
+    const result = await dialog.showOpenDialog(message.senderWindow, message.options)
+
+    // If the user didn't cancel and selected a file, return the result message
+    if (!result.canceled && result.filePaths.length > 0) {
+      const selectedPath = result.filePaths[0]
+      return new RenderDialogMessage(selectedPath)
+    }
+    return
+  }
+}
+```

package/README.zh.md

@@ -1 +1,169 @@
-todo
+#  @virid/renderer
+
+`@virid/renderer` 是electron应用的渲染进程适配器，提供`ToMainMessage`和`FromMainMessage`的自动路由功能与主进程报道功能。
+
+## 🌟 核心设计理念
+
+在 `@virid/renderer` 中，渲染进程朝主进程发送消息被抽象为`ToMainMessage`，该消息可以直接通过调度器分发，消息将会通过IPC直接传送到主进程或其他渲染进程并触发对应的`System`。主进程朝渲染进程发送的消息被抽象为`FromMainMessage`，一旦主进程发送了对应的消息，`FromMainMessage`将会自动被投递到调度器触发相应的渲染进程`System`。
+
+- **路由自动注册**：渲染进程窗口开启后，自动向主进程注册自身，以后所有的消息都将携带自身的窗口信息。
+- **类型恢复**：消息在通过IPC通道后，恢复成真正的Message类重新进入`@virid/core`并被调度器识别并分发。实现不同进程的位置无关性。
+- **消息定向与广播**：可以通过其他渲染进程的ID来实现定向通信，或者使用*来广播消息。
+
+## 🔌启用插件
+
+```ts
+import { createVirid } from '@virid/core'
+import { RenderPlugin } from '@virid/renderer'
+const app = createVirid()
+//需要给每个窗口指定一个唯一的windowId来向主进程报道
+app.use(RenderPlugin, {
+  windowId: 'renderer'
+})
+```
+
+## 🛠️ @virid/renderer 核心 API 概览
+
+### `ToMainMessage`
+
+- **功能**：一个特殊的消息基类，可被继承。所有继承自`ToMainMessage`的Message将被发往其他进程
+- **逻辑**：该消息类型需要两个特殊标记，`__virid_target`标记了目的地，`__virid_messageType`标记了在目的地应该被还原为的Message类型
+- **示例**：
+
+```ts
+//在渲染进程
+import { ToMainMessage } from '@virid/renderer'
+// __virid_target=‘main’,说明消息需要发往主进程
+// 当指定__virid_target=‘*’时，消息将会对所有渲染进程广播
+// __virid_messageType: string = 'close-window'，描述了在主进程，该消息将会重新变为的类型
+
+export class CloseWindowMessage extends ToMainMessage {
+  __virid_target = 'main'
+  __virid_messageType: string = 'close-window'
+}
+export class MinimizeWindowMessage extends ToMainMessage {
+  __virid_target = 'main'
+  __virid_messageType: string = 'minimize-window'
+}
+export class MaximizeWindowMessage extends ToMainMessage {
+  __virid_target = 'main'
+  __virid_messageType: string = 'maximize-window'
+}
+```
+
+在主进程，可以通过`@FromRender`结合`FromRenderMessage`来实现对应的转换。详情见`@virid/main` 。
+
+```ts
+//在主进程
+import { FromRenderMessage, FromRenderer, ToRenderMessage } from '@virid/main'
+//这里的每个id都和渲染进程的消息对应
+@FromRenderer('close-window')
+export class CloseWindowMessage extends FromRendererMessage {}
+@FromRenderer('minimize-window')
+export class MinimizeWindowMessage extends FromRendererMessage {}
+@FromRenderer('maximize-window')
+export class MaximizeWindowMessage extends FromRendererMessage {}
+
+// 通过这三个System，可以实现所有窗口的最小化、最大化、关闭功能
+// senderWindow为发送消息的窗口本身
+export class WindowSystem {
+  @System()
+  closeWindow(@Message(CloseWindowMessage) message: CloseWindowMessage) {
+    message.senderWindow.close()
+  }
+  @System()
+  minimizeWindow(@Message(MinimizeWindowMessage) message: MinimizeWindowMessage) {
+    message.senderWindow.minimize()
+  }
+  @System()
+  maximizeWindow(@Message(MaximizeWindowMessage) message: MaximizeWindowMessage) {
+    if (message.senderWindow.isMaximized()) {
+      message.senderWindow.unmaximize()
+    } else {
+      message.senderWindow.maximize()
+    }
+  }
+}
+```
+
+### `FromMainMessage/@FromIpc()`
+
+- **功能**：一个特殊的消息基类，可被继承。所有继承自`FromMainMessage`的Message将在主进程发送消息时自动转换并投递到当前进程的`virid`调度中心
+- **逻辑**：`@FromIpc()`接受一个字符串类型的ID，该ID与主进程中发送的`ToRendererMessage`的ID应该相同。
+- **示例**：
+
+```ts
+//在渲染进程
+import { FromIpc, FromMainMessage, ToMainMessage } 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()
+  }
+}
+```
+
+在主进程，可以通过`@FromRender`结合`FromRenderMessage`来实现对应的转换。详情见`@virid/main` 。
+
+```ts
+//在主进程
+import { FromRendererMessage, FromRenderer, ToRenderMessage } from '@virid/main'
+
+// @FromRender('open-dialog')表明，当上面的渲染进程调用OpenDialogMessage.send(options)时
+// 主进程的OpenDialogMessage将被自动投递，因此下面的openDialog System将被virid自动调用
+// 当openDialog执行完毕，将返回一个RenderDialogMessage，该RenderDialogMessage标记了目的地与类型
+// 其会转换为渲染进程的OpenDialogMessage并触发渲染进程的System或者Listener执行
+
+@FromRenderer('open-dialog')
+export class OpenDialogMessage extends FromRendererMessage {
+  constructor(
+    public options: {
+      title?: string
+      filters?: Array<{ name: string; extensions: string[] }>
+      properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>
+    }
+  ) {
+    super()
+  }
+}
+
+export class RenderDialogMessage extends ToRendererMessage {
+  __virid_target: string = 'renderer'
+  __virid_messageType: string = 'file-dialog'
+  constructor(public path: string) {
+    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
+  }
+}
+```
+
+
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@virid/renderer",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Electron renderer process adapter for virid, responsible for forwarding and receiving messages from the main process",
   "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",
@@ -34,7 +34,7 @@
   },
   "dependencies": {},
   "peerDependencies": {
-    "@virid/core": "0.1.0"
+    "@virid/core": "0.1.1"
   },
   "scripts": {
     "build": "tsup --config tsup.config.ts",