@netless/window-manager 0.4.31 → 0.4.32

package/dist/typings.d.ts

@@ -1,5 +1,5 @@
 import type Emittery from "emittery";
-import type { AnimationMode, Displayer, DisplayerState, Player, Room, SceneDefinition, SceneState, View } from "white-web-sdk";
+import type { AnimationMode, ApplianceNames, Displayer, DisplayerState, Player, Room, SceneDefinition, SceneState, View } from "white-web-sdk";
 import type { AppContext } from "./App";
 import type { ReadonlyTeleBox, TeleBoxRect } from "@netless/telebox-insider";
 import type { PageState } from "./Page";
@@ -69,6 +69,7 @@ export declare type RegisterParams<AppOptions = any, SetupResult = any, Attribut
     name?: string;
 };
 export declare type AppListenerKeys = keyof AppEmitterEvent;
+export declare type ApplianceIcons = Partial<Record<ApplianceNames, string>>;
 export type { AppContext } from "./App/AppContext";
 export type { ReadonlyTeleBox, TeleBoxRect };
 export type { SceneState, SceneDefinition, View, AnimationMode, Displayer, Room, Player };

package/docs/api.md

@@ -64,7 +64,7 @@ const manager = await WindowManager.mount(
 | disableCameraTransform | [optional] boolean                      |         | 禁用主白板的相机移动                   |
 | prefersColorScheme     | [optional] string                       | light   | auto, light, dark            |
 | debug                  | [optional] boolean                      | false   | 打印日志信息   
-
+| applianceIcons         | [optional] {ApplianceNames, string}     |         | 配置光标使用的教具图片           ｜
 
 <h3 id="register">WindowManager.register</h3>
 

package/docs/app-context.md

@@ -1,10 +1,11 @@
 ## AppContext
 
--   [api](#api)
+- [api](#api)
     - [view](#view)
     - [page](#page)
     - [storage](#storage)
--   [events](#events)
+- [events](#events)
+- [Advanced](#Advanced)
 
 <h2 id="api">API</h2>
 
@@ -16,6 +17,12 @@
     const appId = context.appId;
     ```
 
+- **context.isReplay**
+    
+    类型: `boolean`
+    
+    当前是否回放模式
+
 - **context.getDisplayer()**
 
     在默认情况下 `Displayer` 为白板的 `room` 实例
@@ -32,10 +39,10 @@
 
 - **context.getIsWritable()**
 
-    获取当前状态是否可写
+    获取当前状态是否可写\
+    可以通过监听 `writableChange` 事件获取可写状态的改变
 
     ```ts
-    // isWritable === (room.isWritable && box.readonly)
     const isWritable = context.getIsWritable();
     ```
 
@@ -50,46 +57,31 @@
     box.$footer;
     ```
 
-<h3 id="view">View</h3>
-
-`view` 可以理解为一块白板，可以从 `context` 中拿到这个实例并挂载到 `Dom` 中
-
-- **context.getView()**
+<h3 id="view">挂载白板</h3>
 
-    获取 `view` 实例
-
-    ```ts
-    const view = context.getView();
-    ```
+当应用想要一个可以涂画的白板，可以使用以下接口
 
 - **context.mountView()**
 
-    挂载 view 到指定 dom
+    挂载白板到指定 dom
 
     ```ts
     context.mountView(element);
     ```
 
-- **context.getScenes()**
-
-    `scenes` 在 `addApp` 时传入 `scenePath` 会由 `WindowManager` 创建
-
-    ```ts
-    const scenes = context.getScenes();
-    ```
-
-- **context.setScenePath()**
-
-    切换当前 `view` 到指定的 `scenePath`
-
-    ```ts
-    context.setScenePath("/page/2");
-    ```
-
+**注意** 在调用 `manager` 的 `addApp` 时必须填写 `scenePath` 才可以使用 `view`
+```ts
+manager.addApp({
+    kind: "xxx",
+    options: { // 可选配置
+        scenePath: "/example-path"
+    }
+})
+```
 
 <h3 id="page">Page</h3>
 
-`Page` 是封装后 `scenes` 的一些概念
+白板有多页的概念, 可以通过以下接口添加，切换，以及删除
 
 - **context.addPage()**
 
@@ -116,10 +108,19 @@
     ```ts
     context.prevPage();
     ```
+- **context.removePage()**
+
+    删除一页
+
+    ```ts
+    context.removePage() // 默认删除当前页
+    context.removePage(1) // 也可以指定 index 删除
+    ```
 
 - **context.pageState**
 
-    获取当前所在的 `index` 和一共有多少页
+    获取当前所在的 `index` 和一共有多少页\
+    当想要监听 `pageState` 的变化时, 可以监听 `pageStateChange` 事件获取最新的 `pageState`
 
     ```ts
     context.pageState;
@@ -141,17 +142,97 @@
     context.storage
     ```
 
-- **createStorage()**
+- **context.createStorage(namespace)**
 
     同时你也可以创建多个 `storage` 实例
+    
+    返回: `Storage<State>`
 
     ```ts
-    const defaultState = { count: 0 } // 可选
-    const storage = context.createStorage("store1", defaultState);
+    type State = { count: number };
+    const defaultState = { count: 0 };
+    const storage = context.createStorage<State>("store1", defaultState);
     ```
 
+- **storage.state**
+
+  类型: `State`\
+  默认值: `defaultState`
+
+  在所有客户端之间同步的状态，调用 `storage.setState()` 来改变它。
+
+- **storage.ensureState(partialState)**
+
+  确保 `storage.state` 包含某些初始值，类似于执行了：
+
+  ```js
+  // 这段代码不能直接运行，因为 app.state 是只读的
+  storage.state = { ...partialState, ...storage.state };
+  ```
 
+  **partialState**
 
+  类型: `Partial<State>`
+
+  ```js
+  storage.state; // { a: 1 }
+  storage.ensureState({ a: 0, b: 0 });
+  storage.state; // { a: 1, b: 0 }
+  ```
+
+- **storage.setState(partialState)**
+
+  和 React 的 `setState` 类似，更新 `storage.state` 并同步到所有客户端。
+
+  当设置某个字段为 `undefined` 时，它会被从 `storage.state` 里删除。
+
+  > - 状态同步所需的时间和网络状态与数据大小有关，建议只在 state 里存储必须的数据。
+
+  **partialState**
+
+  类型: `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 }
+  ```
+
+- **storage.addStateChangedListener(listener)**
+
+  它在有人调用 `storage.setState()` 后触发 (包含当前 `storage`)
+
+  返回: `() => void`
+
+  ```js
+  const disposer = storage.addStateChangedListener(diff => {
+    console.log("state changed", diff.oldValue, diff.newValue);
+    disposer(); // remove listener by calling disposer
+  });
+  ```
+
+- **context.dispatchMagixEvent(event, payload)**
+
+  向其他客户端广播事件消息
+
+  ```js
+  context.dispatchMagixEvent("click", { data: "data" });
+  ```
+
+- **context.addMagixEventListener(event, listener)**
+
+  当接收来自其他客户端的消息时(当其他客户端调用'context.dispatchMagixEvent()`时), 它会被触发
+
+  返回: `() => void` a disposer function.
+
+  ```js
+  const disposer = context.addMagixEventListener("click", ({ payload }) => {
+    console.log(payload.data);
+    disposer();
+  });
+
+  context.dispatchMagixEvent("click", { data: "data" });
+  ```
 
 <h2 id="events">events</h2>
 
@@ -203,3 +284,13 @@
         // { index: 0, length: 1 }
     });
     ```
+
+<h2 id="Advanced">Advanced</h2>
+
+- **context.getView()**
+
+    获取 `view` 实例
+
+    ```ts
+    const view = context.getView();
+    ```

package/docs/develop-app.md

@@ -49,7 +49,7 @@ const Counter: NetlessApp<{ count: number }> = {
         countDom.innerText = storage.state.count.toString();
         $content.appendChild(countDom);
 
-        // state 变化回调
+        // 监听 state 变化回调
         storage.addStateChangedListener(diff => {
             if (diff.count) {
                 // diff 会给出 newValue 和 oldValue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netless/window-manager",
-  "version": "0.4.31",
+  "version": "0.4.32",
   "description": "",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",

package/src/Cursor/Cursor.ts

@@ -1,5 +1,4 @@
 import App from "./Cursor.svelte";
-import { ApplianceMap } from "./icons";
 import { ApplianceNames } from "white-web-sdk";
 import { findMemberByUid } from "../Helper";
 import { omit } from "lodash";
@@ -159,8 +158,9 @@ export class Cursor {
 
     private getIcon() {
         if (this.member) {
-            const applianceSrc = ApplianceMap[this.memberApplianceName || ApplianceNames.shape];
-            return applianceSrc || ApplianceMap[ApplianceNames.shape];
+            const icons = this.cursorManager.applianceIcons;
+            const applianceSrc = icons[this.memberApplianceName || ApplianceNames.shape];
+            return applianceSrc || icons[ApplianceNames.shape];
         }
     }
 

package/src/Cursor/index.ts

@@ -5,10 +5,11 @@ import { emitter } from "../InternalEmitter";
 import { SideEffectManager } from "side-effect-manager";
 import { throttle } from "lodash";
 import { WindowManager } from "../index";
-import type { CursorMovePayload } from "../index";
+import type { CursorMovePayload , ApplianceIcons} from "../index";
 import type { PositionType } from "../AttributesDelegate";
 import type { Point, RoomMember, View } from "white-web-sdk";
 import type { AppManager } from "../AppManager";
+import { ApplianceMap } from "./icons";
 
 export type EventType = {
     type: PositionType;
@@ -20,6 +21,7 @@ export type MoveCursorParams = {
     x: number;
     y: number;
 };
+
 export class CursorManager {
     public containerRect?: DOMRect;
     public wrapperRect?: DOMRect;
@@ -28,8 +30,9 @@ export class CursorManager {
     private mainViewElement?: HTMLDivElement;
     private sideEffectManager = new SideEffectManager();
     private store = this.manager.store;
+    public applianceIcons: ApplianceIcons = ApplianceMap;
 
-    constructor(private manager: AppManager, private enableCursor: boolean) {
+    constructor(private manager: AppManager, private enableCursor: boolean, applianceIcons?: ApplianceIcons) {
         this.roomMembers = this.manager.room?.state.roomMembers;
         const wrapper = WindowManager.wrapper;
         if (wrapper) {
@@ -42,6 +45,9 @@ export class CursorManager {
         this.sideEffectManager.add(() => {
             return emitter.on("playgroundSizeChange", () => this.updateContainerRect());
         });
+        if (applianceIcons) {
+            this.applianceIcons = { ...ApplianceMap, ...applianceIcons };
+        }
     }
 
     private onCursorMove = (payload: CursorMovePayload) => {

package/src/index.ts

@@ -29,13 +29,7 @@ import {
     wait,
 } from "./Utils/Common";
 import type { TELE_BOX_STATE, BoxManager } from "./BoxManager";
-import {
-    AppCreateError,
-    AppManagerNotInitError,
-    BindContainerRoomPhaseInvalidError,
-    InvalidScenePath,
-    ParamsInvalidError,
-} from "./Utils/error";
+import * as Errors from "./Utils/error";
 import type { Apps, Position } from "./AttributesDelegate";
 import type {
     Displayer,
@@ -54,7 +48,7 @@ import type {
     SceneState,
 } from "white-web-sdk";
 import type { AppListeners } from "./AppListener";
-import type { NetlessApp, RegisterParams } from "./typings";
+import type { ApplianceIcons, NetlessApp, RegisterParams } from "./typings";
 import type { TeleBoxColorScheme, TeleBoxState } from "@netless/telebox-insider";
 import type { AppProxy } from "./App";
 import type { PublicEvent } from "./callback";
@@ -143,6 +137,7 @@ export type MountParams = {
     debug?: boolean;
     disableCameraTransform?: boolean;
     prefersColorScheme?: TeleBoxColorScheme;
+    applianceIcons?: ApplianceIcons;
 };
 
 export const reconnectRefresher = new ReconnectRefresher({ emitter });
@@ -238,7 +233,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
 
         manager.appManager = new AppManager(manager);
         manager._pageState = new PageStateImpl(manager.appManager);
-        manager.cursorManager = new CursorManager(manager.appManager, Boolean(cursor));
+        manager.cursorManager = new CursorManager(manager.appManager, Boolean(cursor), params.applianceIcons);
         if (containerSizeRatio) {
             manager.containerSizeRatio = containerSizeRatio;
         }
@@ -322,7 +317,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
 
     public bindContainer(container: HTMLElement) {
         if (isRoom(this.displayer) && this.room.phase !== RoomPhase.Connected) {
-            throw new BindContainerRoomPhaseInvalidError();
+            throw new Errors.BindContainerRoomPhaseInvalidError();
         }
         if (WindowManager.isCreated && WindowManager.container) {
             if (WindowManager.container.firstChild) {
@@ -408,19 +403,19 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
                 return this._addApp(params);
             }
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
     private async _addApp<T = any>(params: AddAppParams<T>): Promise<string | undefined> {
         if (this.appManager) {
             if (!params.kind || typeof params.kind !== "string") {
-                throw new ParamsInvalidError();
+                throw new Errors.ParamsInvalidError();
             }
             const appImpl = await appRegister.appClasses.get(params.kind)?.();
             if (appImpl && appImpl.config?.singleton) {
                 if (this.appManager.appProxies.has(params.kind)) {
-                    throw new AppCreateError();
+                    throw new Errors.AppCreateError();
                 }
             }
             const isDynamicPPT = this.setupScenePath(params, this.appManager);
@@ -433,7 +428,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
             const appId = await this.appManager.addApp(params, Boolean(isDynamicPPT));
             return appId;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -443,7 +438,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
             const { scenePath, scenes } = params.options;
             if (scenePath) {
                 if (!isValidScenePath(scenePath)) {
-                    throw new InvalidScenePath();
+                    throw new Errors.InvalidScenePath();
                 }
                 const apps = Object.keys(this.apps || {});
                 for (const appId of apps) {
@@ -646,7 +641,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.mainViewProxy.view;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -654,7 +649,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.mainViewProxy.view.camera;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -662,7 +657,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.mainViewProxy.cameraState;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -674,7 +669,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.boxManager?.boxState;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -686,7 +681,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.boxManager?.prefersColorScheme;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -706,7 +701,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager?.getMainViewSceneDir();
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -731,7 +726,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             return this.appManager.sceneState!;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -739,7 +734,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this._pageState) {
             return this._pageState.toObject();
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 

package/src/typings.ts

@@ -1,6 +1,7 @@
 import type Emittery from "emittery";
 import type {
     AnimationMode,
+    ApplianceNames,
     Displayer,
     DisplayerState,
     Player,
@@ -75,6 +76,8 @@ export type RegisterParams<AppOptions = any, SetupResult = any, Attributes = any
 
 export type AppListenerKeys = keyof AppEmitterEvent;
 
+export type ApplianceIcons = Partial<Record<ApplianceNames, string>>;
+
 export type { AppContext } from "./App/AppContext";
 export type { ReadonlyTeleBox, TeleBoxRect };
 export type { SceneState, SceneDefinition, View, AnimationMode, Displayer, Room, Player };