@netless/window-manager 1.0.0-canary.9 → 1.0.0

package/docs/app-context.md

@@ -1,330 +1,369 @@
 ## AppContext
 
-- [api](#api)
-    - [view](#view)
-    - [page](#page)
-    - [storage](#storage)
-- [events](#events)
-- [box](#box)
+`AppContext` is the context passed in when the plugin runs.
+You can operate the ui of the APP through this object, get the status of the current room, and subscribe to the status change.
+
+- [API](#api)
+     - [View](#view)
+     - [Page](#page)
+     - [Storage](#storage)
+- [UI (box)](#box)
+- [Events](#events)
 - [Advanced](#Advanced)
 
 <h2 id="api">API</h2>
 
 - **context.appId**
 
-    插入 `app` 时生成的唯一 ID
+     Unique ID generated when inserting `app`
 
-    ```ts
-    const appId = context.appId;
-    ```
+     ```ts
+     const appId = context.appId;
+     ```
 
 - **context.isReplay**
     
-    类型: `boolean`
+     Type: `boolean`
     
-    当前是否回放模式
+     Whether the current playback mode
 
-- **context.displayer**
+- **context.getDisplayer()**
 
-    在默认情况下 `Displayer` 为白板的 `room` 实例
+     By default `Displayer` is the `room` instance of the whiteboard
 
-    回放时则为 `Player` 实例
+     A `Player` instance during playback
 
-    ```ts
-    const displayer = context.displayer;
+     ```ts
+     const displayer = context.getDisplayer();
 
-    assert(displayer, room); // 互动房间
-    assert(displayer, player); // 回放房间
-    ```
+     assert(displayer, room); // interactive room
+     assert(displayer, player); // playback room
+     ```
 
 
-- **context.isWritable**
+- **context.getIsWritable()**
 
-    获取当前状态是否可写\
-    可以通过监听 `writableChange` 事件获取可写状态的改变
+     Get whether the current state is writable\
+     You can get the change of writable state by listening to `writableChange` event
 
-    ```ts
-    const isWritable = context.isWritable;
-    ```
+     ```ts
+     const isWritable = context.getIsWritable();
+     ```
 
-- **context.box**
+- **context.getBox()**
 
-    获取当前 app 的 box
+     Get the box of the current app
 
-    类型: `ReadonlyTeleBox`
+     ```ts
+     const box = context.getBox();
 
-    ```ts
-    const box = context.box;
+     box.$content; // main element of the box
+     box.$footer;
+     ```
 
-    box.$content; // box 的 main element
-    box.$footer;
-    ```
+<h3 id="view">Mount whiteboard</h3>
 
-<h3 id="view">创建白板</h3>
+When the application wants a whiteboard that can be drawn on, the following interface can be used
 
-当应用想要一个可以涂画的白板，可以使用以下接口
+- **context.mountView()**
 
-- **context.createWhiteBoardView()**
+     Mount the whiteboard to the specified dom
 
-    创建白板
+     ```ts
+     context.mountView(element);
+     ```
 
-    返回: `WhiteBoardView`
+**Note** When calling `addApp` of `manager`, you must fill in `scenePath` to use `view`
+```ts
+manager.addApp({
+     kind: "xxx",
+     options: { // optional configuration
+         scenePath: "/example-path"
+     }
+})
+```
 
-    ```ts
-    const view = context.createWhiteBoardView();
-    ```
+<h3 id="page">Page</h3>
 
-    ```ts
-    const view = context.createWhiteBoardView(10); // 生成带有 10 页的白板
-    ```
+The whiteboard has the concept of multiple pages, which can be added, switched, and deleted through the following interfaces
 
-- **WhiteBoardView**
+- **context.addPage()**
 
-  白板实例
+     Add a page to `view`
 
-  白板有多页的概念, 可以通过以下接口添加，切换，以及删除
+     ```ts
+     context.addPage() // add a page at the end by default
+     context.addPage({ after: true }) // add a page after the current page
+     context.addPage({ scene: { name: "page2" } }) // pass in page information
+     ```
 
-  - **addPage()**
+- **context.nextPage()**
 
-      添加一页至白板
+     previous page
 
-      ```ts
-      const view = context.createWhiteBoardView();
-      view.addPage() // 默认在最后添加一页
-      context.addPage({ after: true }) // 在当前页后添加一页
-      context.addPage({ scene: { name: "page2" } }) // 传入 page 信息
-      ```
+     ```ts
+     context.nextPage();
+     ```
 
-  - **nextPage()**
+- **context.prevPage()**
 
-      上一页
+     next page
 
-      ```ts
-      const view = context.createWhiteBoardView();
-      view.nextPage();
-      ```
+     ```ts
+     context.prevPage();
+     ```
+- **context.removePage()**
 
-  - **prevPage()**
+     delete a page
 
-      下一页
+     ```ts
+     context.removePage() // delete the current page by default
+     context.removePage(1) // You can also specify index to delete
+     ```
 
-      ```ts
-      const view = context.createWhiteBoardView();
-      view.prevPage();
-      ```
-  - **removePage()**
+- **context.pageState**
 
-      删除一页
+     Get the current `index` and how many pages there are\
+     When you want to monitor the change of `pageState`, you can listen to the `pageStateChange` event to get the latest `pageState`
 
-      ```ts
-      const view = context.createWhiteBoardView();
-      view.removePage() // 默认删除当前页
-      view.removePage(1) // 也可以指定 index 删除
-      ```
-
-  - **pageState**
-
-    类型: `PageState`
-
-    ```ts
-    type PageState {
-        index: number
-        length: number
-    }
-    ```
-
-    ```ts
-    const view = context.createWhiteBoardView();
-    view.pageState // PageState
-    ```
-
-  - **pageState$**
-
-    订阅 `pageState` 的变化
-
-    ```ts
-    const view = context.createWhiteBoardView();
-    view.pageState$.subscribe(pageState => {
-        console.log("pageStateChange", pageState)
-    })
-    ```
+     ```ts
+     context.pageState;
+     // {
+     //    index: number,
+     //    length: number,
+     // }
+     ```
 
 <h3 id="storage">storage</h3>
 
-存储和同步状态，以及发送事件的一系列集合
+Store and synchronize state, and send a collection of events
 
 - **context.storage**
 
-    默认创建的 storage 实例
+     Storage instance created by default
 
-    ```ts
-    context.storage
-    ```
+     ```ts
+     context.storage
+     ```
 
 - **context.createStorage(namespace)**
 
-    同时你也可以创建多个 `storage` 实例
+     At the same time you can also create multiple `storage` instances
     
-    返回: `Storage<State>`
+     Returns: `Storage<State>`
 
-    ```ts
-    type State = { count: number };
-    const defaultState = { count: 0 };
-    const storage = context.createStorage<State>("store1", defaultState);
-    ```
+     ```ts
+     type State = { count: number };
+     const defaultState = { count: 0 };
+     const storage = context.createStorage<State>("store1", defaultState);
+     ```
 
 - **storage.state**
 
-  类型: `State`\
-  默认值: `defaultState`
+   Type: `State`\
+   Default: `defaultState`
 
-  在所有客户端之间同步的状态，调用 `storage.setState()` 来改变它。
+   State synchronized between all clients, call `storage.setState()` to change it.
 
 - **storage.ensureState(partialState)**
 
-  确保 `storage.state` 包含某些初始值，类似于执行了：
+   Make sure `storage.state` contains some initial values, something like doing:
 
-  ```js
-  // 这段代码不能直接运行，因为 app.state 是只读的
-  storage.state = { ...partialState, ...storage.state };
-  ```
+   ```js
+   // This code cannot be run directly because app.state is read-only
+   storage.state = { ...partialState, ...storage.state };
+   ```
 
-  **partialState**
+   **partialState**
 
-  类型: `Partial<State>`
+   Type: `Partial<State>`
 
-  ```js
-  storage.state; // { a: 1 }
-  storage.ensureState({ a: 0, b: 0 });
-  storage.state; // { a: 1, b: 0 }
-  ```
+   ```js
+   storage.state; // { a: 1 }
+   storage.ensureState({ a: 0, b: 0 });
+   storage.state; // { a: 1, b: 0 }
+   ```
 
 - **storage.setState(partialState)**
 
-  和 React 的 `setState` 类似，更新 `storage.state` 并同步到所有客户端。
+   Similar to React's `setState`, update `storage.state` and sync to all clients.
 
-  当设置某个字段为 `undefined` 时，它会被从 `storage.state` 里删除。
+   When setting a field to `undefined`, it will be removed from `storage.state`.
 
-  > - 状态同步所需的时间和网络状态与数据大小有关，建议只在 state 里存储必须的数据。
+   > The time required for state synchronization and the network state are related to the data size. It is recommended to only store necessary data in the state.
 
-  **partialState**
+   **partialState**
 
-  类型: `Partial<State>`
+   Type: `Partial<State>`
 
-  ```js
-  storage.state; //=> { count: 0, a: 1 }
-  storage.setState({ count: storage.state.count + 1, b: 2 });
-  storage.state; //=> { count: 1, a: 1, b: 2 }
-  ```
+   ```js
+   storage.state; //=> { count: 0, a: 1 }
+   storage.setState({ count: storage.state.count + 1, b: 2 });
+   storage.state; //=> { count: 1, a: 1, b: 2 }
+   ```
 
 - **storage.addStateChangedListener(listener)**
 
-  它在有人调用 `storage.setState()` 后触发 (包含当前 `storage`)
+   It fires after someone calls `storage.setState()` (including the current `storage`)
 
-  返回: `() => void`
+   return: `() => void`
 
-  ```js
-  const disposer = storage.addStateChangedListener(diff => {
-    console.log("state changed", diff.oldValue, diff.newValue);
-    disposer(); // remove listener by calling disposer
-  });
-  ```
+   ```js
+   const disposer = storage.addStateChangedListener(diff => {
+     console.log("state changed", diff.oldValue, diff.newValue);
+     disposer(); // remove listener by calling disposer
+   });
+   ```
 
 - **context.dispatchMagixEvent(event, payload)**
 
-  向其他客户端广播事件消息
+   Broadcast event messages to other clients
 
-  ```js
-  context.dispatchMagixEvent("click", { data: "data" });
-  ```
+   ```js
+   context.dispatchMagixEvent("click", { data: "data" });
+   ```
 
 - **context.addMagixEventListener(event, listener)**
 
-  当接收来自其他客户端的消息时(当其他客户端调用'context.dispatchMagixEvent()`时), 它会被触发
+   It is triggered when receiving messages from other clients (when other clients call `context.dispatchMagixEvent()`)
+
+   Returns: `() => void` a disposer function.
+
+   ```js
+   const disposer = context.addMagixEventListener("click", ({ payload }) => {
+     console.log(payload.data);
+     disposer();
+   });
+
+   context.dispatchMagixEvent("click", { data: "data" });
+   ```
+
+<h2>UI (box)</h2>
+
+Box is the default UI created by whiteboard for all apps.
+All operable UI parts of the application are within the bounds of the box.
+
+- **context.getBox()**
 
-  返回: `() => void` a disposer function.
+     get box
+     Return type: `ReadonlyTeleBox`
 
-  ```js
-  const disposer = context.addMagixEventListener("click", ({ payload }) => {
-    console.log(payload.data);
-    disposer();
-  });
+- **box.mountStyles()**
 
-  context.dispatchMagixEvent("click", { data: "data" });
-  ```
+     Mount styles to `box`
+     Parameters: `string | HTMLStyleElement`
+
+     ```js
+     const box = context. getBox();
+     box. mountStyles(`
+         .app-span {
+             color: red;
+         }
+     `)
+     ```
+
+- **box.mountContent()**
+
+     Mount element to `box`
+     Parameters: `HTMLElement`
+
+     ```js
+     const box = context. getBox();
+     const content = document. createElement("div");
+     box. mountContent(context);
+     ```
+
+- **box.mountFooter()**
+
+     Mount element to `footer` of `box`
+     Parameters: `HTMLElement`
+
+     ```js
+     const box = context. getBox();
+     const footer = document. createElement("div");
+     box. mountFooter(context);
+     ```
 
 <h2 id="events">events</h2>
 
 - **destroy**
 
-    app 被关闭时发送
+     Sent when the app is closed
 
-    ```ts
-    context.emitter.on("destroy", () => {
-        // release your listeners
-    });
-    ```
+     ```ts
+     context.emitter.on("destroy", () => {
+         // release your listeners
+     });
+     ```
 
 - **writableChange**
 
-    白板可写状态切换时触发
+     Triggered when the whiteboard's writable state is switched
 
-    ```ts
-    context.emitter.on("writableChange", isWritable => {
-        //
-    });
-    ```
+     ```ts
+     context.emitter.on("writableChange", isWritable => {
+         //
+     });
+     ```
 
 - **focus**
 
-    当前 app 获得焦点或者失去焦点时触发
-
-    ```ts
-    context.emitter.on("focus", focus => {
-        //
-    });
-    ```
+     Triggered when the current app gains or loses focus
 
-<h2 id="Advanced">Advanced</h2>
+     ```ts
+     context.emitter.on("focus", focus => {
+         //
+     });
+     ```
 
-- **context.getView()**
+- **pageStateChange**
 
-    获取 `view` 实例
+     `PageState`
 
-    ```ts
-    const view = context.view;
-    ```
+     ```ts
+     type PateState {
+         index: number;
+         length: number;
+     }
+     ```
 
-<h2 id="box">box</h2>
+     Triggered when the current page number and the total page number change
 
-    `box` 为应用窗口本身
+     ```ts
+     context.emitter.on("pageStateChange", pageState => {
+         // { index: 0, length: 1 }
+     });
+     ```
+- **roomStageChange**
 
-    类型: `ReadonlyTeleBox`
+     Triggered when the state of the room changes\
+     For example, when teaching aids are switched
 
-- **contentStageRect**
+     ```js
+     context.emitter.on("roomStageChange", stage => {
+         if (state. memberState) {
+             console.log("appliance change to", state.memberState.currentApplianceName);
+         }
+     });
+     ```
 
-    可同步区域\
-    在这个区域中的内容, `WindowManager` 会确保所有的端都可以看到
+     or when the number of people in the current room changes
 
-    类型: `TeleboxRect`
+     ```js
+      context.emitter.on("roomStageChange", stage => {
+         if (state. roomMembers) {
+             console.log("current room members change", state.roomMembers);
+         }
+     });
+     ```
+     For detailed status introduction, please refer to https://developer.netless.link/javascript-zh/home/business-state-management
 
-    ```ts
-    interface TeleboxRect {
-        readonly x: number;
-        readonly y: number;
-        readonly width: number;
-        readonly height: number;
-    }
-    ```
+<h2 id="Advanced">Advanced</h2>
 
-    ```ts
-    box.contentStageRect
-    ```
+- **context.getView()**
 
-    订阅 `contextStateRect` 的变化
+     Get `view` instance
 
-    ```ts
-    box._contentStageRect$.subscribe(rect => {
-        console.log("contentStageRect changed", rect);
-    });
-    ```
+     ```ts
+     const view = context.getView();
+     ```

package/docs/basic.md

@@ -1,64 +1,63 @@
-# 基础教程
-`WindowManager` 内置了 `DocsViewer` 和 `MediaPlayer` 用来播放 PPT 和音视频
+# Basic Tutorial
+`WindowManager` has built-in `DocsViewer` and `MediaPlayer` to play PPT and audio and video
 
-## 打开动态/静态 PPT
+## Open dynamic/static PPT
 ```typescript
 import { BuiltinApps } from "@netless/window-manager";
 
 const appId = await manager.addApp({
-    kind: BuiltinApps.DocsViewer,
-    options: {
-        scenePath: "/docs-viewer", // 定义 ppt 所在的 scenePath
-        title: "docs1", // 可选
-        scenes: [], // SceneDefinition[] 静态/动态 Scene 数据
-    },
+     kind: BuiltinApps.DocsViewer,
+     options: {
+         scenePath: "/docs-viewer", // define the scenePath where the ppt is located
+         title: "docs1", // optional
+         scenes: [], // SceneDefinition[] static/dynamic Scene data
+     },
 });
 ```
 
-## 打开音视频
+## Open audio and video
 ```typescript
 import { BuiltinApps } from "@netless/window-manager";
 
 const appId = await manager.addApp({
-    kind: BuiltinApps.MediaPlayer,
-    options: {
-        title: "test.mp3", // 可选
-    },
-    attributes: {
-        src: "xxxx", // 音视频 url
-    },
+     kind: BuiltinApps.MediaPlayer,
+     options: {
+         title: "test.mp3", // optional
+     },
+     attributes: {
+         src: "xxxx", // audio and video url
+     },
 });
 ```
  
 
-## 查询所有的 App
+## Query all apps
 ```typescript
 const apps = manager.queryAll();
 ```
 
-## 查询单个 APP
+## Query a single APP
 ```typescript
 const app = manager.queryOne(appId);
-``` 
+```
 
-## 关闭 App
+## Close App
 ```typescript
 manager.closeApp(appId);
 ```
 
 ## events
 
-### 窗口最小化最大化
+### Minimize and maximize the window
 ```typescript
 manager.emitter.on("boxStateChange", state => {
-    // maximized | minimized | normal
+     // maximized | minimized | normal
 });
 ```
 
-### 视角跟随模式
+### Camera follow mode
 ```typescript
 manager.emitter.on("broadcastChange", state => {
-    // state: number | undefined
+     // state: number | undefined
 });
 ```
-