@rerun-io/web-viewer 0.16.1 → 0.17.0-alpha.2

package/README.md

@@ -41,7 +41,7 @@ viewer.stop();
 ```
 
 The `rrd` in the snippet above should be a URL pointing to either:
-- A hosted `.rrd` file, such as <https://app.rerun.io/version/0.16.1/examples/dna.rrd>
+- A hosted `.rrd` file, such as <https://app.rerun.io/version/0.17.0-alpha.2/examples/dna.rrd>
 - A WebSocket connection to the SDK opened via the [`serve`](https://www.rerun.io/docs/reference/sdk-operating-modes#serve) API
 
 If `rrd` is not set, the Viewer will display the same welcome screen as <https://app.rerun.io>.

package/index.d.ts

@@ -5,9 +5,9 @@ declare module '@rerun-io/web-viewer' {
 		 *
 		 * @param rrd URLs to `.rrd` files or WebSocket connections to our SDK.
 		 * @param parent The element to attach the canvas onto.
-		 * @param hide_welcome_screen Whether to hide the welcome screen.
+		 * @param options Whether to hide the welcome screen.
 		 * */
-		start(rrd?: string | string[] | undefined, parent?: HTMLElement | undefined, hide_welcome_screen?: boolean | undefined): Promise<void>;
+		start(rrd?: string | string[] | null | undefined, parent?: HTMLElement | null | undefined, options?: WebViewerOptions | null | undefined): Promise<void>;
 		/**
 		 * Returns `true` if the viewer is ready to connect to data sources.
 		 */
@@ -48,6 +48,35 @@ declare module '@rerun-io/web-viewer' {
 		 *
 		 * */
 		open_channel(channel_name?: string): LogChannel;
+		/**
+		 * Force a panel to a specific state.
+		 *
+		 * */
+		override_panel_state(panel: Panel, state: PanelState): void;
+		/**
+		 * Toggle panel overrides set via `override_panel_state`.
+		 */
+		toggle_panel_overrides(): void;
+		/**
+		 * Toggle fullscreen mode.
+		 *
+		 * This does nothing if `allow_fullscreen` was not set to `true` when starting the viewer.
+		 *
+		 * Fullscreen mode works by updating the underlying `<canvas>` element's `style`:
+		 * - `position` to `fixed`
+		 * - width/height/top/left to cover the entire viewport
+		 *
+		 * When fullscreen mode is toggled off, the style is restored to its previous values.
+		 *
+		 * When fullscreen mode is toggled on, any other instance of the viewer on the page
+		 * which is already in fullscreen mode is toggled off. This means that it doesn't
+		 * have to be tracked manually.
+		 *
+		 * This functionality can also be directly accessed in the viewer:
+		 * - The maximize/minimize top panel button
+		 * - The `Toggle fullscreen` UI command (accessible via the command palette, CTRL+P)
+		 */
+		toggle_fullscreen(): void;
 		#private;
 	}
 	export class LogChannel {
@@ -70,6 +99,59 @@ declare module '@rerun-io/web-viewer' {
 		close(): void;
 		#private;
 	}
+	export type Panel = "top" | "blueprint" | "selection" | "time";
+	export type PanelState = "hidden" | "collapsed" | "expanded";
+	export type Backend = "webgpu" | "webgl";
+	export type CanvasRect = {
+		width: string;
+		height: string;
+		top: string;
+		left: string;
+		bottom: string;
+		right: string;
+	};
+	export type CanvasStyle = {
+		canvas: CanvasRect & {
+			position: string;
+			transition: string;
+		};
+		document: {
+			overflow: string;
+		};
+	};
+	export type FullscreenOff = {
+		on: false;
+		saved_style: null;
+		saved_rect: null;
+	};
+	export type FullscreenOn = {
+		on: true;
+		saved_style: CanvasStyle;
+		saved_rect: DOMRect;
+	};
+	export type FullscreenState = (FullscreenOff | FullscreenOn);
+	export type WebViewerOptions = {
+		/**
+		 * Use a different example manifest.
+		 */
+		manifest_url?: string | undefined;
+		/**
+		 * Force the viewer to use a specific rendering backend.
+		 */
+		render_backend?: Backend | undefined;
+		/**
+		 * Whether to hide the welcome screen in favor of a simpler one.
+		 */
+		hide_welcome_screen?: boolean | undefined;
+		/**
+		 * Whether to allow the viewer to enter fullscreen mode.
+		 */
+		allow_fullscreen?: boolean | undefined;
+	};
+	export type FullscreenOptions = {
+		get_state: () => boolean;
+		on_toggle: () => void;
+	};
 }
 
 declare module '@rerun-io/web-viewer/re_viewer.js' {
@@ -119,13 +201,17 @@ declare module '@rerun-io/web-viewer/re_viewer.js' {
   export class WebHandle {
 	free(): void;
 
-	constructor();
+	constructor(app_options: any);
   /**
   * - `url` is an optional URL to either an .rrd file over http, or a Rerun WebSocket server.
   * - `manifest_url` is an optional URL to an `examples_manifest.json` file over http.
   * - `force_wgpu_backend` is an optional string to force a specific backend, either `webgl` or `webgpu`.
   * */
-	start(canvas_id: string, url?: string, manifest_url?: string, force_wgpu_backend?: string, hide_welcome_screen?: boolean): Promise<void>;
+	start(canvas_id: string): Promise<void>;
+
+	toggle_panel_overrides(): void;
+
+	override_panel_state(panel: string, state?: string): void;
 
 	destroy(): void;
 

package/index.d.ts.map

@@ -4,6 +4,12 @@
 	"names": [
 		"WebViewer",
 		"LogChannel",
+		"Panel",
+		"PanelState",
+		"Backend",
+		"FullscreenOff",
+		"FullscreenOn",
+		"FullscreenState",
 		"set_email",
 		"IntoUnderlyingByteSource",
 		"IntoUnderlyingSink",
@@ -18,5 +24,5 @@
 		null,
 		null
 	],
-	"mappings": ";cAuBaA,SAASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqJTC,UAAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBClKPC,SAASA;;eAGZC,wBAAwBA;;;;;;;;;;;;;;eAuBxBC,kBAAkBA;;;;;;;;;;eAmBlBC,oBAAoBA;;;;;;;;eAapBC,SAASA"
+	"mappings": ";cAiEaA,SAASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqVTC,UAAUA;;;;;;;;;;;;;;;;;;;;aAvXkCC,KAAKA;aAEZC,UAAUA;aAE3BC,OAAOA;;;;;;;;;;;;;;;;;;aAayBC,aAAaA;;;;;aAEJC,YAAYA;;;;;aAEzCC,eAAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBC1C5CC,SAASA;;eAGZC,wBAAwBA;;;;;;;;;;;;;;eAuBxBC,kBAAkBA;;;;;;;;;;eAmBlBC,oBAAoBA;;;;;;;;eAapBC,SAASA"
 }

package/index.js

@@ -12,6 +12,13 @@ async function load() {
   return WebHandle;
 }
 
+/**
+ * Used to prevent multiple viewers from being fullscreen at the same time.
+ *
+ * @type {(() => void) | null}
+ */
+let _minimize_current_fullscreen_viewer = null;
+
 /** @returns {string} */
 function randomId() {
   const bytes = new Uint8Array(16);
@@ -21,7 +28,44 @@ function randomId() {
     .join("");
 }
 
+/**
+ * @typedef {"top" | "blueprint" | "selection" | "time"} Panel
+ *
+ * @typedef {"hidden" | "collapsed" | "expanded"} PanelState
+ *
+ * @typedef {"webgpu" | "webgl"} Backend
+ *
+ * @typedef {{
+ *   width: string; height: string;
+ *   top: string; left: string;
+ *   bottom: string; right: string;
+ * }} CanvasRect
+ *
+ * @typedef {{
+ *   canvas: CanvasRect & { position: string; transition: string; };
+ *   document: { overflow: string };
+ * }} CanvasStyle
+ *
+ * @typedef {{ on: false; saved_style: null; saved_rect: null }} FullscreenOff
+ *
+ * @typedef {{ on: true; saved_style: CanvasStyle; saved_rect: DOMRect }} FullscreenOn
+ *
+ * @typedef {(FullscreenOff | FullscreenOn)} FullscreenState
+ *
+ * @typedef WebViewerOptions
+ * @property {string} [manifest_url] Use a different example manifest.
+ * @property {Backend} [render_backend] Force the viewer to use a specific rendering backend.
+ * @property {boolean} [hide_welcome_screen] Whether to hide the welcome screen in favor of a simpler one.
+ * @property {boolean} [allow_fullscreen] Whether to allow the viewer to enter fullscreen mode.
+ *
+ * @typedef FullscreenOptions
+ * @property {() => boolean} get_state
+ * @property {() => void} on_toggle
+ */
+
 export class WebViewer {
+  #id = randomId();
+
   /** @type {(import("./re_viewer.js").WebHandle) | null} */
   #handle = null;
 
@@ -31,33 +75,63 @@ export class WebViewer {
   /** @type {'ready' | 'starting' | 'stopped'} */
   #state = "stopped";
 
+  /**
+   * @type {FullscreenState}
+   */
+  #fullscreen_state = {
+    on: false,
+    saved_style: null,
+    saved_rect: null,
+  };
+
+  #allow_fullscreen = false;
+
   /**
    * Start the viewer.
    *
-   * @param {string | string[]} [rrd] URLs to `.rrd` files or WebSocket connections to our SDK.
-   * @param {HTMLElement} [parent] The element to attach the canvas onto.
-   * @param {boolean} [hide_welcome_screen] Whether to hide the welcome screen.
+   * @param {string | string[] | null} [rrd] URLs to `.rrd` files or WebSocket connections to our SDK.
+   * @param {HTMLElement | null} [parent] The element to attach the canvas onto.
+   * @param {WebViewerOptions | null} [options] Whether to hide the welcome screen.
    * @returns {Promise<void>}
    */
-  async start(rrd, parent = document.body, hide_welcome_screen = false) {
+  async start(rrd, parent, options) {
+    parent ??= document.body;
+    options ??= {};
+
+    this.#allow_fullscreen = options.allow_fullscreen || false;
+
     if (this.#state !== "stopped") return;
     this.#state = "starting";
 
     this.#canvas = document.createElement("canvas");
-    this.#canvas.id = randomId();
+    this.#canvas.id = this.#id;
     parent.append(this.#canvas);
 
-    let WebHandle_class = await load();
+    /**
+     * @typedef AppOptions
+     * @property {string} [url]
+     * @property {string} [manifest_url]
+     * @property {Backend} [render_backend]
+     * @property {boolean} [hide_welcome_screen]
+     * @property {Partial<{[K in Panel]: PanelState}>} [panel_state_overrides]
+     * @property {FullscreenOptions} [fullscreen]
+     *
+     * @typedef {(import("./re_viewer.js").WebHandle)} _WebHandle
+     * @typedef {{ new(app_options?: AppOptions): _WebHandle }} WebHandleConstructor
+     */
+
+    let WebHandle_class = /** @type {WebHandleConstructor} */ (await load());
     if (this.#state !== "starting") return;
 
-    this.#handle = new WebHandle_class();
-    await this.#handle.start(
-      this.#canvas.id,
-      undefined,
-      undefined,
-      undefined,
-      hide_welcome_screen,
-    );
+    const fullscreen = this.#allow_fullscreen
+      ? {
+          get_state: () => this.#fullscreen_state.on,
+          on_toggle: () => this.toggle_fullscreen(),
+        }
+      : undefined;
+
+    this.#handle = new WebHandle_class({ ...options, fullscreen });
+    await this.#handle.start(this.#canvas.id);
     if (this.#state !== "starting") return;
 
     if (this.#handle.has_panicked()) {
@@ -65,7 +139,6 @@ export class WebViewer {
     }
 
     this.#state = "ready";
-
     if (rrd) {
       this.open(rrd);
     }
@@ -134,6 +207,11 @@ export class WebViewer {
    */
   stop() {
     if (this.#state === "stopped") return;
+    if (this.#allow_fullscreen && this.#canvas) {
+      const state = this.#fullscreen_state;
+      if (state.on) this.#minimize(this.#canvas, state);
+    }
+
     this.#state = "stopped";
 
     this.#canvas?.remove();
@@ -142,6 +220,8 @@ export class WebViewer {
 
     this.#canvas = null;
     this.#handle = null;
+    this.#fullscreen_state.on = false;
+    this.#allow_fullscreen = false;
   }
 
   /**
@@ -154,20 +234,174 @@ export class WebViewer {
    * @returns {LogChannel}
    */
   open_channel(channel_name = "rerun-io/web-viewer") {
-    if (!this.#handle) throw new Error("...");
+    if (!this.#handle) {
+      throw new Error(
+        `attempted to open channel \"${channel_name}\" in a stopped web viewer`,
+      );
+    }
     const id = crypto.randomUUID();
     this.#handle.open_channel(id, channel_name);
     const on_send = (/** @type {Uint8Array} */ data) => {
-      if (!this.#handle) throw new Error("...");
+      if (!this.#handle) {
+        throw new Error(
+          `attempted to send data through channel \"${channel_name}\" to a stopped web viewer`,
+        );
+      }
       this.#handle.send_rrd_to_channel(id, data);
     };
     const on_close = () => {
-      if (!this.#handle) throw new Error("...");
+      if (!this.#handle) {
+        throw new Error(
+          `attempted to send data through channel \"${channel_name}\" to a stopped web viewer`,
+        );
+      }
       this.#handle.close_channel(id);
     };
     const get_state = () => this.#state;
     return new LogChannel(on_send, on_close, get_state);
   }
+
+  /**
+   * Force a panel to a specific state.
+   *
+   * @param {Panel} panel
+   * @param {PanelState} state
+   */
+  override_panel_state(panel, state) {
+    if (!this.#handle) {
+      throw new Error(
+        `attempted to set ${panel} panel to ${state} in a stopped web viewer`,
+      );
+    }
+    this.#handle.override_panel_state(panel, state);
+  }
+
+  /**
+   * Toggle panel overrides set via `override_panel_state`.
+   */
+  toggle_panel_overrides() {
+    if (!this.#handle) {
+      throw new Error(
+        `attempted to toggle panel overrides in a stopped web viewer`,
+      );
+    }
+    this.#handle.toggle_panel_overrides();
+  }
+
+  /**
+   * Toggle fullscreen mode.
+   *
+   * This does nothing if `allow_fullscreen` was not set to `true` when starting the viewer.
+   *
+   * Fullscreen mode works by updating the underlying `<canvas>` element's `style`:
+   * - `position` to `fixed`
+   * - width/height/top/left to cover the entire viewport
+   *
+   * When fullscreen mode is toggled off, the style is restored to its previous values.
+   *
+   * When fullscreen mode is toggled on, any other instance of the viewer on the page
+   * which is already in fullscreen mode is toggled off. This means that it doesn't
+   * have to be tracked manually.
+   *
+   * This functionality can also be directly accessed in the viewer:
+   * - The maximize/minimize top panel button
+   * - The `Toggle fullscreen` UI command (accessible via the command palette, CTRL+P)
+   */
+  toggle_fullscreen() {
+    if (!this.#allow_fullscreen) return;
+
+    if (!this.#handle || !this.#canvas) {
+      throw new Error(
+        `attempted to toggle fullscreen mode in a stopped web viewer`,
+      );
+    }
+
+    const state = this.#fullscreen_state;
+    if (state.on) {
+      this.#minimize(this.#canvas, state);
+    } else {
+      this.#maximize(this.#canvas);
+    }
+  }
+
+  #minimize = (
+    /** @type {HTMLCanvasElement} */ canvas,
+    /** @type {FullscreenOn} */ { saved_style, saved_rect },
+  ) => {
+    this.#fullscreen_state = {
+      on: false,
+      saved_style: null,
+      saved_rect: null,
+    };
+
+    if (this.#fullscreen_state.on) return;
+
+    canvas.style.width = saved_rect.width + "px";
+    canvas.style.height = saved_rect.height + "px";
+    canvas.style.top = saved_rect.top + "px";
+    canvas.style.left = saved_rect.left + "px";
+    canvas.style.bottom = saved_rect.bottom + "px";
+    canvas.style.right = saved_rect.right + "px";
+
+    setTimeout(
+      () =>
+        requestAnimationFrame(() => {
+          for (const key in saved_style.canvas) {
+            // @ts-expect-error
+            canvas.style[key] = saved_style.canvas[key];
+          }
+          for (const key in saved_style.document) {
+            // @ts-expect-error
+            document.body.style[key] = saved_style.document[key];
+          }
+        }),
+      100,
+    );
+
+    _minimize_current_fullscreen_viewer = null;
+  };
+
+  #maximize = (/** @type {HTMLCanvasElement} */ canvas) => {
+    _minimize_current_fullscreen_viewer?.();
+
+    const style = canvas.style;
+
+    /** @type {CanvasStyle} */
+    const saved_style = {
+      canvas: {
+        position: style.position,
+        width: style.width,
+        height: style.height,
+        top: style.top,
+        left: style.left,
+        bottom: style.bottom,
+        right: style.right,
+        transition: style.transition,
+      },
+      document: { overflow: document.body.style.overflow },
+    };
+    const saved_rect = canvas.getBoundingClientRect();
+
+    style.position = "fixed";
+    style.width = `100%`;
+    style.height = `100%`;
+    style.top = `0px`;
+    style.left = `0px`;
+    style.bottom = `0px`;
+    style.right = `0px`;
+    style.transition = ["width", "height", "top", "left", "bottom", "right"]
+      .map((p) => `${p} 0.1s linear`)
+      .join(", ");
+    document.body.style.overflow = "hidden";
+
+    this.#fullscreen_state = {
+      on: true,
+      saved_style,
+      saved_rect,
+    };
+
+    _minimize_current_fullscreen_viewer = () => this.toggle_fullscreen();
+  };
 }
 
 export class LogChannel {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rerun-io/web-viewer",
-  "version": "0.16.1",
+  "version": "0.17.0-alpha.2",
   "description": "Embed the Rerun web viewer in your app",
   "licenses": [
     {
@@ -12,9 +12,10 @@
   ],
   "scripts": {
     "build:wasm": "cargo run -p re_dev_tools -- build-web-viewer --release -g --module -o rerun_js/web-viewer",
-    "build:wasm:debug": "cargo run -p re_dev_tools -- build-web-viewer --module -o rerun_js/web-viewer",
     "build:types": "tsc --noEmit && dts-buddy",
-    "build": "npm run build:wasm && npm run build:types"
+    "build": "npm run build:wasm && npm run build:types",
+    "build:wasm:debug": "cargo run -p re_dev_tools -- build-web-viewer --debug --module -o rerun_js/web-viewer",
+    "build:debug": "npm run build:wasm:debug && npm run build:types"
   },
   "repository": {
     "type": "git",

package/re_viewer.d.ts

@@ -69,20 +69,25 @@ export class IntoUnderlyingSource {
 export class WebHandle {
   free(): void;
 /**
+* @param {any} app_options
 */
-  constructor();
+  constructor(app_options: any);
 /**
 * - `url` is an optional URL to either an .rrd file over http, or a Rerun WebSocket server.
 * - `manifest_url` is an optional URL to an `examples_manifest.json` file over http.
 * - `force_wgpu_backend` is an optional string to force a specific backend, either `webgl` or `webgpu`.
 * @param {string} canvas_id
-* @param {string | undefined} [url]
-* @param {string | undefined} [manifest_url]
-* @param {string | undefined} [force_wgpu_backend]
-* @param {boolean | undefined} [hide_welcome_screen]
 * @returns {Promise<void>}
 */
-  start(canvas_id: string, url?: string, manifest_url?: string, force_wgpu_backend?: string, hide_welcome_screen?: boolean): Promise<void>;
+  start(canvas_id: string): Promise<void>;
+/**
+*/
+  toggle_panel_overrides(): void;
+/**
+* @param {string} panel
+* @param {string | undefined} [state]
+*/
+  override_panel_state(panel: string, state?: string): void;
 /**
 */
   destroy(): void;