@netless/fastboard 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netless/fastboard",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "An open sourced sdk based on white-web-sdk.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.es.js",
@@ -22,6 +22,14 @@
       "default": "./dist/vue.es.js",
       "types": "./src/vue.ts"
     },
+    "./svelte": {
+      "node": {
+        "import": "./dist/svelte.es.js",
+        "require": "./dist/svelte.cjs.js"
+      },
+      "default": "./dist/svelte.es.js",
+      "types": "./src/svelte.ts"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -83,5 +91,5 @@
     "tippy.js": "^6.3.7",
     "vue-demi": "^0.12.1"
   },
-  "readme": "# @netless/fastboard\n\nA whiteboard starter, based on [white-web-sdk](https://www.npmjs.com/package/white-web-sdk), [@netless/window-manager](https://www.npmjs.com/package/@netless/window-manager)\nand [netless-app](https://github.com/netless-io/netless-app).\n\n## 目录\n\n- [安装](#install)\n- [使用](#usage)\n- [进阶](./docs/advanced.md)\n- [开发](#开发)\n\n<h2 id=\"install\">安装</h2>\n\n```bash\nnpm add @netless/fastboard @netless/window-manager white-web-sdk react react-dom\n```\n\n<h2 id=\"usage\">使用</h2>\n\n<h3 id=\"mount-whiteboard\">挂载白板</h3>\n\n> 原生 `javascript`\n\n```js\nimport { createWhiteboardApp } from \"@netless/fastboard\";\n\nlet whiteboard = await createWhiteboardApp({\n  target: document.getElementById(\"whiteboard\"),\n  // [1]\n  sdkConfig: {\n    appIdentifier: \"whiteboard-appid\",\n  },\n  // [2]\n  joinRoom: {\n    uid: \"unique_id_for_each_client\",\n    uuid: \"room-uuid\",\n    roomToken: \"NETLESSROOM_...\",\n  },\n  // [3]\n  managerConfig: {\n    cursor: true,\n  },\n});\n```\n\n> 使用 `React`\n\n```typescript\nimport { useFastboard, FastBoardConfig } from \"@netless/fastboard\";\nimport ReactDOM from \"react-dom\";\n\nconst config: FastBoardConfig = {\n  sdkConfig: {\n    appIdentifier: \"whiteboard-appid\",\n  },\n  joinRoom: {\n    uid: \"unique_id_for_each_client\",\n    uuid: \"room-uuid\",\n    roomToken: \"NETLESSROOM_...\",\n  },\n};\n\nfunction App() {\n  const [app, ref] = useFastboard(config);\n  return <div ref={ref} />;\n}\nReactDOM.render(<App />, document.getElementById(\"root\"));\n```\n\n[1] 关于 SDK 更多配置请看 [构造 WhiteWebSDK](https://developer.netless.link/javascript-zh/home/construct-white-web-sdk)\n\n[2] 加入房间更多配置请看 [构造 Room 与 Player 对象](https://developer.netless.link/javascript-zh/home/construct-room-and-player)\n\n[3] 配置 `WindowManager` 请看 [WindowManager](https://github.com/netless-io/window-manager#mount)\n\n### 使用 APPS\n\n**注意:** 需要先安装对应的 APP\n\n```bash\nnpm add @netless/app-slide\n```\n\n```typescript\n// 插入动态 PPTX 至白板\nconst appId = await whiteboard.insertDocs({\n  fileType: \"pptx\",\n  params: {\n    scenePath: `/ppt/${uuid}`, // [1]\n    title: \"a.pptx\",\n    taskId: \"1234567...\", // [2]\n    url: \"https://convertcdn.netless.link/dynamicConvert\", // [3]\n  },\n});\n\n// 插入 PDF/静态 PPT 至白板\nconst appId = await whiteboard.insertDocs({\n  fileType: \"pdf\", // or ppt\n  options: {\n    scenePath: `/pdf${uuid}`,\n    title: \"a.pdf\", // 可选\n    scenes: [], // SceneDefinition[] 静态/动态 Scene 数据\n  },\n});\n\n// 插入音频/视频至白板\nconst appId = await whiteboard.manager.addApp({\n  kind: \"MediaPlayer\",\n  options: {\n    title: \"test.mp3\", // 可选\n  },\n  attributes: {\n    src: \"xxxx\", // 音视频 url\n  },\n});\n```\n\n更多 `app` 请看 [netless-app](#https://github.com/netless-io/netless-app)\n\n## Develop\n\n```bash\npnpm i\n# upgrade dependencies\npnpm up -Li\n# build and see bundle size\npnpm build\nopen node_modules/.visualizer/stats.html\n```\n\n## License\n\nMIT @ [netless](https://github.com/netless-io)\n"
+  "readme": "# @netless/fastboard\n\nA whiteboard starter, based on [white-web-sdk](https://www.npmjs.com/package/white-web-sdk), [@netless/window-manager](https://www.npmjs.com/package/@netless/window-manager)\nand [netless-app](https://github.com/netless-io/netless-app).\n\n## 目录\n\n- [安装](#install)\n- [使用](#usage)\n- [进阶](./docs/advanced.md)\n- [开发](#开发)\n\n<h2 id=\"install\">安装</h2>\n\n```bash\nnpm add @netless/fastboard @netless/window-manager white-web-sdk react react-dom\n```\n\n<h2 id=\"usage\">使用</h2>\n\n<h3 id=\"mount-whiteboard\">挂载白板</h3>\n\n> 原生 `javascript`\n\n```js\nimport { createWhiteboardApp } from \"@netless/fastboard\";\n\nlet app = await createWhiteboardApp({\n  target: document.getElementById(\"whiteboard\"),\n  // [1]\n  sdkConfig: {\n    appIdentifier: \"whiteboard-appid\",\n  },\n  // [2]\n  joinRoom: {\n    uid: \"unique_id_for_each_client\",\n    uuid: \"room-uuid\",\n    roomToken: \"NETLESSROOM_...\",\n  },\n  // [3]\n  managerConfig: {\n    cursor: true,\n  },\n});\n```\n\n> 使用 `React`\n\n```jsx\nimport { createWhiteboardApp, Fastboard } from \"@netless/fastboard\";\nimport ReactDOM from \"react-dom\";\n\nlet app = await createWhiteboardApp({\n  /* ... */\n});\n\nfunction App() {\n  return <Fastboard app={app} />;\n}\nReactDOM.render(<App />, document.getElementById(\"root\"));\n```\n\n[1] 关于 SDK 更多配置请看 [构造 WhiteWebSDK](https://developer.netless.link/javascript-zh/home/construct-white-web-sdk)\n\n[2] 加入房间更多配置请看 [构造 Room 与 Player 对象](https://developer.netless.link/javascript-zh/home/construct-room-and-player)\n\n[3] 配置 `WindowManager` 请看 [WindowManager](https://github.com/netless-io/window-manager#mount)\n\n### 使用 APPS\n\n**注意:** 需要先安装对应的 APP\n\n```bash\nnpm add @netless/app-slide\n```\n\n```typescript\n// 插入动态 PPTX 至白板\nconst appId = await app.insertDocs({\n  fileType: \"pptx\",\n  params: {\n    scenePath: `/ppt/${uuid}`, // [1]\n    title: \"a.pptx\",\n    taskId: \"1234567...\", // [2]\n    url: \"https://convertcdn.netless.link/dynamicConvert\", // [3]\n  },\n});\n\n// 插入 PDF/静态 PPT 至白板\nconst appId = await app.insertDocs({\n  fileType: \"pdf\", // or ppt\n  options: {\n    scenePath: `/pdf${uuid}`,\n    title: \"a.pdf\", // 可选\n    scenes: [], // SceneDefinition[] 静态/动态 Scene 数据\n  },\n});\n\n// 插入音频/视频至白板\nconst appId = await app.manager.addApp({\n  kind: \"MediaPlayer\",\n  options: {\n    title: \"test.mp3\", // 可选\n  },\n  attributes: {\n    src: \"xxxx\", // 音视频 url\n  },\n});\n```\n\n更多 `app` 请看 [netless-app](#https://github.com/netless-io/netless-app)\n\n## Develop\n\n```bash\npnpm i\n# upgrade dependencies\npnpm up -Li\n# build and see bundle size\npnpm build\nopen node_modules/.visualizer/stats.html\n```\n\n## License\n\nMIT @ [netless](https://github.com/netless-io)\n"
 }

package/src/WhiteboardApp.ts

@@ -1,33 +1,41 @@
+import type { ConversionResponse, SceneDefinition } from "white-web-sdk";
 import type {
   InsertDocsParams,
+  InsertMediaParams,
   Language,
   Layout,
   WhiteboardAppConfig,
 } from "./internal";
-import { Instance } from "./internal";
+import { genUID, Instance, makeSlideParams } from "./internal";
 
-export type { Language, Layout, WhiteboardAppConfig, InsertDocsParams };
+export type {
+  Language,
+  Layout,
+  WhiteboardAppConfig,
+  InsertMediaParams,
+  InsertDocsParams,
+};
 
 export class WhiteboardApp {
   private readonly _instance: Instance;
 
-  constructor(readonly config: WhiteboardAppConfig) {
+  public constructor(readonly config: WhiteboardAppConfig) {
     this._instance = new Instance(config);
   }
 
-  get room() {
+  public get room() {
     return this._instance.room;
   }
 
-  get manager() {
+  public get manager() {
     return this._instance.manager;
   }
 
-  get sdk() {
+  public get sdk() {
     return this._instance.sdk;
   }
 
-  get i18n() {
+  public get i18n() {
     return this._instance.i18n;
   }
 
@@ -39,11 +47,12 @@ export class WhiteboardApp {
     return this._instance.collector;
   }
 
-  public bindElement(
-    target?: HTMLElement | null,
-    collector?: HTMLElement | null
-  ) {
-    this._instance.bindElement(target || null, collector || null);
+  public bindElement(target?: HTMLElement | null) {
+    this._instance.bindElement(target || null);
+  }
+
+  public bindCollector(collector?: HTMLElement | null) {
+    this._instance.bindCollector(collector || null);
   }
 
   public get layout() {
@@ -54,8 +63,65 @@ export class WhiteboardApp {
     this._instance.updateLayout(layout);
   }
 
-  public insertDocs(params: InsertDocsParams) {
-    return this._instance.insertDocs(params);
+  public insertMedia(params: InsertMediaParams) {
+    this._instance.insertMedia(params);
+  }
+
+  /**
+   * Insert PDF/PPTX from conversion result.
+   * @param status https://developer.netless.link/server-en/home/server-conversion#get-query-task-conversion-progress
+   */
+  public insertDocs(
+    filename: string,
+    status: ConversionResponse
+  ): Promise<string | undefined>;
+
+  /**
+   * Manual way.
+   */
+  public insertDocs(params: InsertDocsParams): Promise<string | undefined>;
+
+  public insertDocs(
+    arg1: string | InsertDocsParams,
+    arg2?: ConversionResponse
+  ) {
+    if (typeof arg1 === "object" && "fileType" in arg1) {
+      return this._instance.insertDocs(arg1);
+    } else if (arg2 && arg2.status !== "Finished") {
+      throw new Error("[WhiteboardApp] cannot insert a converting doc");
+    } else if (arg2 && arg2.progress) {
+      const scenes: SceneDefinition[] = arg2.progress.convertedFileList.map(
+        (f, i) => ({
+          name: String(i + 1),
+          ppt: {
+            src: f.conversionFileUrl,
+            width: f.width,
+            height: f.height,
+            previewURL: f.preview,
+          },
+        })
+      );
+      const uid = genUID();
+      const scenePath = `/${arg2.uuid}/${uid}`;
+      const { scenesWithoutPPT, taskId, url } = makeSlideParams(scenes);
+      if (taskId && url) {
+        return this._instance.insertDocs({
+          fileType: "pptx",
+          scenePath,
+          taskId,
+          title: arg1,
+          url,
+          scenes: scenesWithoutPPT,
+        });
+      } else {
+        return this._instance.insertDocs({
+          fileType: "pdf",
+          scenePath,
+          scenes,
+          title: arg1,
+        });
+      }
+    }
   }
 
   public insertCodeEditor() {

package/src/components/PlayerControl/hooks.ts

@@ -1,8 +1,9 @@
 import type { DependencyList } from "react";
 import type { Player } from "white-web-sdk";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { PlayerPhase } from "white-web-sdk";
+import { useLastValue } from "../../internal/hooks";
 
 const EMPTY_ARRAY: DependencyList = [];
 
@@ -12,14 +13,6 @@ function useForceUpdate() {
   return useCallback(() => forceUpdate_({}), EMPTY_ARRAY);
 }
 
-function useLastValue<T>(value: T) {
-  const ref = useRef<T>(value);
-  useEffect(() => {
-    ref.current = value;
-  }, [value]);
-  return ref.current;
-}
-
 export function usePlayer(player?: Player | null) {
   const togglePlay = useCallback(() => {
     if (player) {

package/src/index.ts

@@ -15,7 +15,7 @@ export {
   type PlayerControlProps,
 } from "./components/PlayerControl";
 export * from "./WhiteboardApp";
-export * from "./hooks";
+export * from "./react";
 
 export const register = WindowManager.register.bind(WindowManager);
 

package/src/internal/Instance.tsx

@@ -6,6 +6,7 @@ import type { i18n } from "i18next";
 
 import React, { createContext, useContext } from "react";
 import ReactDOM from "react-dom";
+import { BuiltinApps } from "@netless/window-manager";
 
 import { Root } from "../components/Root";
 import { mountWhiteboard } from "./mount-whiteboard";
@@ -18,6 +19,11 @@ export interface AcceptParams {
   readonly i18n: i18n;
 }
 
+export interface InsertMediaParams {
+  title: string;
+  src: string;
+}
+
 export interface InsertDocsStatic {
   readonly fileType: "pdf" | "ppt";
   readonly scenePath: string;
@@ -31,6 +37,7 @@ export interface InsertDocsDynamic {
   readonly taskId: string;
   readonly title?: string;
   readonly url?: string;
+  readonly scenes?: SceneDefinition[];
 }
 
 export type InsertDocsParams = InsertDocsStatic | InsertDocsDynamic;
@@ -110,15 +117,21 @@ export class Instance {
   target: HTMLElement | null = null;
   collector: HTMLElement | null = null;
 
-  bindElement(target: HTMLElement | null, collector: HTMLElement | null) {
-    if (this.target && target) {
+  bindElement(target: HTMLElement | null) {
+    if (this.target && this.target !== target) {
       ReactDOM.unmountComponentAtNode(this.target);
     }
     this.target = target;
-    this.collector = collector;
     this.forceUpdate();
   }
 
+  bindCollector(collector: HTMLElement | null) {
+    this.collector = collector;
+    if (this.manager && collector) {
+      this.manager.bindCollectorContainer(collector);
+    }
+  }
+
   updateLayout(layout: Layout | undefined) {
     this.config.layout = layout;
     this.forceUpdate();
@@ -154,10 +167,9 @@ export class Instance {
     if (!this.manager) {
       throw new Error(`[WhiteboardApp] mounted, but not found window manager`);
     }
+    this.manager.bindContainer(node);
     if (this.collector) {
-      this.manager.bindContainer(node, this.collector);
-    } else {
-      this.manager.bindContainer(node);
+      this.manager.bindCollectorContainer(this.collector);
     }
   }
 
@@ -198,6 +210,7 @@ export class Instance {
           options: {
             scenePath: params.scenePath,
             title: params.title,
+            scenes: params.scenes,
           },
           attributes: {
             taskId: params.taskId,
@@ -237,6 +250,17 @@ export class Instance {
     });
   }
 
+  insertMedia({ title, src }: InsertMediaParams) {
+    if (!this.manager) {
+      throw new Error(`[WhiteboardApp] cannot insert app before mounted`);
+    }
+    return this.manager.addApp({
+      kind: BuiltinApps.MediaPlayer,
+      options: { title },
+      attributes: { src },
+    });
+  }
+
   async changeLanguage(language: Language) {
     try {
       await this.i18n?.changeLanguage(language);

package/src/internal/helpers.ts

@@ -1,3 +1,5 @@
+import type { SceneDefinition } from "white-web-sdk";
+
 export function noop() {
   return;
 }
@@ -40,3 +42,45 @@ export class Lock {
     }
   };
 }
+
+// Copy from https://github.com/crimx/side-effect-manager/blob/main/src/gen-uid.ts
+const SOUP =
+  "!#%()*+,-./:;=?@[]^_`{|}~" +
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const SOUP_LEN = SOUP.length;
+const ID_LEN = 20;
+const reusedIdCarrier = Array(ID_LEN);
+
+export const genUID = (): string => {
+  for (let i = 0; i < ID_LEN; i++) {
+    reusedIdCarrier[i] = SOUP.charAt(Math.random() * SOUP_LEN);
+  }
+  return reusedIdCarrier.join("");
+};
+
+export function makeSlideParams(scenes: SceneDefinition[]) {
+  const scenesWithoutPPT: SceneDefinition[] = [];
+  let taskId = "";
+  let url = "";
+
+  // e.g. "ppt(x)://cdn/prefix/dynamicConvert/{taskId}/1.slide"
+  const pptSrcRE = /^pptx?(?<prefix>:\/\/\S+?dynamicConvert)\/(?<taskId>\w+)\//;
+
+  for (const { name, ppt } of scenes) {
+    // make sure scenesWithoutPPT.length === scenes.length
+    scenesWithoutPPT.push({ name });
+
+    if (!ppt || !ppt.src.startsWith("ppt")) {
+      continue;
+    }
+    const match = pptSrcRE.exec(ppt.src);
+    if (!match || !match.groups) {
+      continue;
+    }
+    taskId = match.groups.taskId;
+    url = "https" + match.groups.prefix;
+    break;
+  }
+
+  return { scenesWithoutPPT, taskId, url };
+}

package/src/internal/hooks.ts

@@ -0,0 +1,9 @@
+import { useEffect, useRef } from "react";
+
+export function useLastValue<T>(value: T) {
+  const ref = useRef<T>(value);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref.current;
+}

package/src/react.tsx

@@ -0,0 +1,26 @@
+import type { WhiteboardApp } from "./index";
+
+import React, { useEffect, useRef } from "react";
+import { useLastValue } from "./internal/hooks";
+
+/**
+ * @example
+ * let app = await createWhiteboardApp(config)
+ * <Fastboard app={app} />
+ * await app.dispose()
+ */
+export function Fastboard({ app }: { app?: WhiteboardApp | null }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const previous = useLastValue(app);
+
+  useEffect(() => {
+    if (previous && previous !== app) {
+      previous.bindElement(null);
+    }
+    if (app) {
+      app.bindElement(ref.current);
+    }
+  }, [app, previous]);
+
+  return <div className="fastboard" ref={ref} />;
+}

package/src/style.scss

@@ -9,6 +9,12 @@
 @import "./components/Toolbar/Toolbar.scss";
 @import "./components/PlayerControl/PlayerControl.scss";
 
+.fastboard {
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
 .tippy-box.fastboard-tip {
   color: #eee;
   background-color: rgba($color: #000000, $alpha: 0.95);

package/src/hooks.ts

@@ -1,53 +0,0 @@
-import type { WhiteboardApp, WhiteboardAppConfig } from "./WhiteboardApp";
-
-import { useEffect, useState } from "react";
-import { createWhiteboardApp } from "./index";
-
-export type FastBoardConfig = WhiteboardAppConfig;
-
-/**
- * @example
- * const [app, ref] = useFastboard({ sdkConfig, joinRoom })
- * if (app) {
- *   app.insertDocs({...})
- * }
- * return <div style={{ width: '100%', height: '100%' }} ref={ref} />
- */
-export function useFastboard(config: FastBoardConfig): readonly [
-  app: WhiteboardApp | null,
-  ref: (div: HTMLDivElement | null) => void,
-  collectorRef: (div: HTMLDivElement | null) => void
-] & {
-  readonly app: WhiteboardApp | null;
-  readonly ref: (div: HTMLDivElement | null) => void;
-  readonly collectorRef: (div: HTMLDivElement | null) => void;
-} {
-  const [app, setApp] = useState<WhiteboardApp | null>(null);
-  const [currentTarget, ref] = useState<HTMLDivElement | null>(null);
-  const [collector, collectorRef] = useState<HTMLDivElement | null>(null);
-
-  useEffect(() => {
-    let isMounted = true;
-    const promise = createWhiteboardApp(config).then(app => {
-      if (isMounted) setApp(app);
-    });
-    return () => {
-      isMounted = false;
-      promise.then(() => app?.dispose());
-    };
-    // ignore config and app change
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  useEffect(() => {
-    if (app) {
-      app.bindElement(currentTarget, collector);
-    }
-  }, [app, collector, currentTarget]);
-
-  return Object.assign([app, ref, collectorRef] as const, {
-    app,
-    ref,
-    collectorRef,
-  });
-}