@perspective-dev/viewer 5.3.1 → 5.5.0

package/src/rust/custom_elements/viewer.rs

@@ -38,7 +38,7 @@ use crate::js::*;
 use crate::presentation::*;
 use crate::queries::*;
 use crate::root::Root;
-use crate::session::{ResetOptions, TableLoadState};
+use crate::session::{MissingTable, ResetOptions, TableLoadState};
 use crate::tasks::*;
 use crate::utils::*;
 use crate::workspace::{Panel, PanelId, Workspace};
@@ -61,11 +61,18 @@ extern "C" {
     #[wasm_bindgen(typescript_type = "PanelOptions")]
     pub type JsPanelOptions;
 
-    /// `restore()` options dict
-    /// (`{ panel?: string, suppress_errors?: boolean }`).
+    /// The `restore()` options dict.
     #[wasm_bindgen(typescript_type = "RestoreOptions")]
     pub type JsRestoreOptions;
 
+    /// The `restoreWorkspace()` options dict.
+    #[wasm_bindgen(typescript_type = "RestoreWorkspaceOptions")]
+    pub type JsRestoreWorkspaceOptions;
+
+    /// The `addPanel()` options dict.
+    #[wasm_bindgen(typescript_type = "AddPanelOptions")]
+    pub type JsAddPanelOptions;
+
     /// `addPanel()` argument: a new panel's initial config — `table`
     /// REQUIRED.
     #[wasm_bindgen(typescript_type = "ViewerConfigInitial")]
@@ -84,9 +91,9 @@ extern "C" {
     #[wasm_bindgen(typescript_type = "GetClientOptions")]
     pub type JsGetClientOptions;
 
-    /// `restoreWorkspace()` argument: a workspace config update.
-    #[wasm_bindgen(typescript_type = "WorkspaceConfigUpdate")]
-    pub type JsWorkspaceConfigUpdate;
+    /// `getView` options dict (`{ mode?: GetViewMode, panel?: string }`).
+    #[wasm_bindgen(typescript_type = "GetViewOptions")]
+    pub type JsGetViewOptions;
 
     /// `saveWorkspace()` options dict (`{ full_palette?: boolean }`).
     #[wasm_bindgen(typescript_type = "SaveWorkspaceOptions")]
@@ -121,14 +128,15 @@ struct ResizeDimensions {
 /// falling back to `Default` on absence or a malformed argument (matching the
 /// `ResizeOptions` precedent — an options bag is a best-effort convenience,
 /// not a hard-validated payload).
-fn parse_options<T, U>(options: Option<T>) -> U
+fn parse_options<T, U>(options: Option<T>) -> ApiResult<U>
 where
     T: Into<JsValue>,
     U: Default + for<'a> serde::Deserialize<'a>,
 {
-    options
-        .and_then(|o| o.into_serde_ext().ok())
-        .unwrap_or_default()
+    match options {
+        None => Ok(U::default()),
+        Some(x) => Ok(x.into_serde_ext()?),
+    }
 }
 
 /// The `<perspective-viewer>` custom element.
@@ -196,6 +204,28 @@ impl PerspectiveViewerElement {
         })
     }
 
+    /// Re-stamp the global-filter overlay on every panel not in `fresh` and
+    /// re-render those whose overlay changed.
+    async fn rerender_retained_overlays(&self, fresh: &[PanelId]) -> ApiResult<()> {
+        let retained = self
+            .workspace
+            .panels()
+            .into_iter()
+            .filter(|panel| !fresh.contains(&panel.id))
+            .filter(|panel| stamp_global_overlay(&self.workspace, &panel.id, &panel.session))
+            .collect::<Vec<_>>();
+
+        join_all(retained.iter().map(|panel| async move {
+            apply_and_render(&panel.session, &panel.renderer, ViewConfigUpdate::default())?.await?;
+            Ok(())
+        }))
+        .await
+        .into_iter()
+        .collect::<ApiResult<Vec<_>>>()?;
+
+        Ok(())
+    }
+
     fn layout_element(&self) -> Option<RegularLayout> {
         self.elem
             .shadow_root()?
@@ -512,31 +542,13 @@ impl PerspectiveViewerElement {
                         .expect("just-reserved panel is present")
                 });
 
-                // Carrying `Some(notify)` marks this load as the reservation's
-                // owner — the only call that may place or discard it below.
                 (panel, Some(self.layout_changed_notify()))
             },
         };
 
-        // A `Table` payload targets this panel's engines; a `Client` registers
-        // inertly against it. Selecting the panel here (not at construction)
-        // keeps the registry race safe — by `load()` time real plugins have
-        // registered.
         let session = panel.session;
         let renderer = panel.renderer;
-
-        // Open the pending-load window SYNCHRONOUSLY, at the call site — this
-        // is what fixes the ordering. The payload's RESET disposition (a
-        // `Table` resets the view; a `Client` does not) is unknown until the
-        // promise resolves, but the window's POSITION on the config-commit
-        // stream is fixed NOW. A `restore()` a caller fires immediately after
-        // this unawaited `load()` (the React prop-binding pattern, which has
-        // no async ordering guarantees) commits INTO this window's journal and
-        // is replayed over the reset base if the payload proves to be a
-        // `Table` — so a moved-async reset can no longer clobber a later
-        // commit. See `SESSION_CONFIG_COHERENCE_PLAN.md`.
         let generation = session.begin_pending_load();
-
         clone!(self.workspace, self.presentation);
         Ok(ApiFuture::new_throttled(async move {
             let _effect = effect;
@@ -734,7 +746,11 @@ impl PerspectiveViewerElement {
     /// await viewer.eject({client: "remote"});
     /// ```
     pub fn eject(&mut self, options: Option<JsClientOptions>) -> ApiFuture<()> {
-        let ClientOptions { client } = parse_options(options);
+        let ClientOptions { client } = match parse_options(options) {
+            Ok(x) => x,
+            Err(x) => return ApiFuture::new_err(x),
+        };
+
         // Default target: the active panel's client, or — when the active panel
         // is unbound (`load(Client)` is now inert) — the default client.
         let Some(target) = client
@@ -770,32 +786,59 @@ impl PerspectiveViewerElement {
         eject_client_panels(&self.workspace, &self.root, target, ids)
     }
 
-    /// Get the underlying [`View`] for this viewer.
+    /// Get a [`View`] for a panel of this viewer, as currently configured by
+    /// the user.
     ///
-    /// Use this method to get promgrammatic access to the [`View`] as currently
-    /// configured by the user, for e.g. serializing as an
-    /// [Apache Arrow](https://arrow.apache.org/) before passing to another
-    /// library.
+    /// # Arguments
     ///
-    /// The [`View`] returned by this method is owned by the
-    /// [`PerspectiveViewerElement`] and may be _invalidated_ by
-    /// [`View::delete`] at any time. Plugins which rely on this [`View`] for
-    /// their [`HTMLPerspectiveViewerPluginElement::draw`] implementations
-    /// should treat this condition as a _cancellation_ by silently aborting on
-    /// "View already deleted" errors from method calls.
+    /// - `mode` - which [`View`] to return:
+    ///   - `"live"` (default) - the panel's own [`View`], which the viewer
+    ///     replaces on every config change and deletes when auto-paused or
+    ///     [`PerspectiveViewerElement::delete`]d, so calls on it may fail with
+    ///     "View already deleted", it must never be deleted by the caller, and
+    ///     it rejects with `No View for panel "<name>"` while none is bound
+    ///     (auto-paused or not yet rendered).
+    ///   - `"clone"` - a new [`View`] built from the panel's effective config
+    ///     (global filter included), independent of the render lifecycle, which
+    ///     the caller owns and must [`View::delete`].
+    ///   - `"auto"` - `"live"` when the panel has a bound [`View`], else
+    ///     `"clone"`.
+    /// - `panel` - the target panel, or the active panel when omitted.
+    ///
+    /// Plugins which rely on the live [`View`] for their
+    /// [`HTMLPerspectiveViewerPluginElement::draw`] implementations should
+    /// treat "View already deleted" as a _cancellation_ by silently aborting.
     ///
     /// # JavaScript Examples
     ///
     /// ```javascript
     /// const view = await viewer.getView();
     /// ```
+    ///
+    /// Export every panel without borrowing the viewer's own [`View`]:
+    ///
+    /// ```javascript
+    /// for (const panel of viewer.getPanelNames()) {
+    ///     const view = await viewer.getView({ panel, mode: "clone" });
+    ///     const arrow = await view.to_arrow();
+    ///     await view.delete();
+    /// }
+    /// ```
     #[wasm_bindgen]
-    pub fn getView(&self, options: Option<JsPanelOptions>) -> ApiFuture<View> {
-        let PanelOptions { panel: name } = parse_options(options);
+    pub fn getView(&self, options: Option<JsGetViewOptions>) -> ApiFuture<View> {
         let this = self.clone();
         ApiFuture::new(async move {
+            let GetViewOptions { mode, panel: name } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
-            Ok(panel.session.get_view().ok_or("No table set")?.into())
+            match (mode.unwrap_or_default(), panel.session.get_view()) {
+                (GetViewMode::Live | GetViewMode::Auto, Some(view)) => Ok(view.into()),
+                (GetViewMode::Live, None) => {
+                    Err(format!("No View for panel \"{}\"", panel.id.as_str()).into())
+                },
+                (GetViewMode::Clone, _) | (GetViewMode::Auto, None) => {
+                    Ok(panel.session.create_detached_view().await?.into())
+                },
+            }
         })
     }
 
@@ -806,9 +849,9 @@ impl PerspectiveViewerElement {
     /// [`View::get_config`])
     #[wasm_bindgen]
     pub fn getViewConfig(&self, options: Option<JsPanelOptions>) -> ApiFuture<JsViewConfig> {
-        let PanelOptions { panel: name } = parse_options(options);
         let this = self.clone();
         ApiFuture::new(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
             let config = if let Some(ctx) = panel.renderer.render_context() {
                 (*ctx.view_config).clone()
@@ -839,12 +882,12 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn getTable(&self, options: Option<JsGetTableOptions>) -> ApiFuture<Table> {
-        let GetTableOptions {
-            wait: wait_for_table,
-            panel: name,
-        } = parse_options(options);
         let this = self.clone();
         ApiFuture::new(async move {
+            let GetTableOptions {
+                wait: wait_for_table,
+                panel: name,
+            } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
             if !wait_for_table.unwrap_or_default()
                 && let Some(ctx) = panel.renderer.render_context()
@@ -884,12 +927,12 @@ impl PerspectiveViewerElement {
         &self,
         options: Option<JsGetClientOptions>,
     ) -> ApiFuture<perspective_js::Client> {
-        let GetClientOptions {
-            wait: wait_for_client,
-            panel: name,
-        } = parse_options(options);
         let this = self.clone();
         ApiFuture::new(async move {
+            let GetClientOptions {
+                wait: wait_for_client,
+                panel: name,
+            } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
             if !wait_for_client.unwrap_or_default()
                 && let Some(ctx) = panel.renderer.render_context()
@@ -920,7 +963,7 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn getRenderStats(&self, options: Option<JsPanelOptions>) -> ApiResult<JsValue> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let panel = self.resolve_panel(name)?;
         Ok(JsValue::from_serde_ext(
             &panel.renderer.render_timer().get_stats(),
@@ -1018,12 +1061,13 @@ impl PerspectiveViewerElement {
     /// - `options.panel` - The panel to target, or the active panel when
     ///   omitted.
     /// - `options.suppress_errors` - when `true`, a failed restore only rejects
-    ///   the returned `Promise`; the error is NOT committed to the viewer's
-    ///   visible error state and the session remains usable. The view config is
-    ///   rolled back to its pre-call value, so a rejected patch cannot re-merge
-    ///   into a later restore. Element-level state the call already applied
-    ///   (theme, title, a plugin swap) is NOT undone — restore a known-good
-    ///   config to recover those exactly.
+    ///   the returned `Promise` and rolls the view config back, leaving the
+    ///   viewer's visible error state and any element-level state the call
+    ///   already applied (theme, title, plugin, a successful `table` change)
+    ///   untouched.
+    /// - `options.wait_for_table` - when `true`, a `table` no loaded client
+    ///   hosts yet leaves the panel empty and pending until the table is
+    ///   created, instead of the default error.
     ///
     /// # JavaScript Examples
     ///
@@ -1045,20 +1089,23 @@ impl PerspectiveViewerElement {
         update: JsViewerConfigUpdate,
         options: Option<JsRestoreOptions>,
     ) -> JsVoidPromise {
-        let RestoreOptions {
-            panel: name,
-            suppress_errors,
-        } = parse_options(options);
-
-        let errors = if suppress_errors.unwrap_or_default() {
-            RestoreErrors::Suppress
-        } else {
-            RestoreErrors::Publish
-        };
-
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         let fut = ApiFuture::new_throttled(async move {
+            let RestoreOptions {
+                panel: name,
+                suppress_errors,
+                wait_for_table,
+            } = parse_options(options)?;
+
+            let errors = if suppress_errors.unwrap_or_default() {
+                RestoreErrors::Suppress
+            } else {
+                RestoreErrors::Publish
+            };
+
+            let missing = MissingTable::from_wait(wait_for_table);
+
             let _effect = effect;
             let id = name.map(PanelId::from);
             let mut update = ViewerConfigUpdate::decode(&update)?;
@@ -1092,19 +1139,6 @@ impl PerspectiveViewerElement {
             };
 
             if !matches!(settings, OptionalUpdate::Missing) {
-                // Through `ToggleSettingsInit` — the SAME full choreography
-                // the toolbar toggle drives (presize every visible plugin
-                // to its post-toggle box, then the exactness-finalizer
-                // resize) — NOT the bare `ToggleSettingsComplete` leaf,
-                // which only re-renders the pane. The pane is the outer
-                // `SplitPanel` (no `before-resize` event) and the host box
-                // is unchanged, so a leaf-only toggle left every canvas
-                // plugin CSS-stretched at its old backing size.
-                //
-                // No `set_settings_before_open` here: `is_settings_open` is
-                // Init's toggle-vs-no-op DISPATCH state, so pre-writing the
-                // target makes every call resolve as a no-op. Init owns the
-                // write, as it does for the toolbar and `toggleConfig`.
                 let (sender, receiver) = channel::<ApiResult<JsValue>>();
                 this.root.borrow().as_ref().into_apierror()?.send_message(
                     PerspectiveViewerMsg::ToggleSettingsInit(Some(settings), false, Some(sender)),
@@ -1123,6 +1157,7 @@ impl PerspectiveViewerElement {
                         RestoreMode::Existing { active },
                         update,
                         errors,
+                        missing,
                     )
                     .await
                 },
@@ -1135,6 +1170,7 @@ impl PerspectiveViewerElement {
                         RestoreMode::Existing { active: true },
                         update,
                         errors,
+                        missing,
                     )
                     .await
                 },
@@ -1147,6 +1183,7 @@ impl PerspectiveViewerElement {
                         id,
                         *config,
                         None,
+                        missing,
                     )
                     .await?;
                     Ok(())
@@ -1157,25 +1194,47 @@ impl PerspectiveViewerElement {
         js_sys::Promise::from(fut).unchecked_into()
     }
 
-    /// Restore the ENTIRE element from a [`WorkspaceConfigUpdate`]
-    /// (`{version, active?, layout, panels, ...}`) —
-    /// the multi-panel counterpart of [`Self::restore`]. Every existing panel
-    /// is replaced by the `panels` entries, and the layout tree + master/detail
-    /// cross-filter state re-applied. Unlike [`Self::restore`], this never
-    /// falls back to the single-panel path.
+    /// Apply a [`WorkspaceConfigUpdate`] to the element — the multi-panel
+    /// counterpart of [`Self::restore`] and like it a field-wise update, where
+    /// an absent field is unchanged, `null` resets and a value replaces.
+    ///
+    /// # Arguments
+    ///
+    /// - `update` - The workspace config update: a [`Self::saveWorkspace`]
+    ///   token replaces every panel (`panels` is the whole set), while a token
+    ///   without `panels` keeps them and `layout`, `active` and `masters` name
+    ///   them by their existing ids.
+    /// - `options.wait_for_table` - when `true`, a panel whose `table` no
+    ///   loaded client hosts yet is created empty and pending until the table
+    ///   is created, instead of the default error.
     ///
     /// # JavaScript Examples
     ///
     /// ```javascript
     /// await viewer.restoreWorkspace(await otherViewer.saveWorkspace());
     /// ```
-    pub fn restoreWorkspace(&self, update: JsWorkspaceConfigUpdate) -> JsVoidPromise {
-        let update: JsViewerConfigUpdate = update.unchecked_into();
+    ///
+    /// Cross-filter the current panels without re-creating them:
+    ///
+    /// ```javascript
+    /// await viewer.restoreWorkspace({ global_filters: [["Region", "==", "West"]] });
+    /// ```
+    pub fn restoreWorkspace(
+        &self,
+        update: JsWorkspaceConfigUpdate,
+        options: Option<JsRestoreWorkspaceOptions>,
+    ) -> JsVoidPromise {
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         let fut = ApiFuture::new(async move {
             let _effect = effect;
+            let RestoreWorkspaceOptions { wait_for_table } = parse_options(options)?;
+            let missing = MissingTable::from_wait(wait_for_table);
             let (contents, eject_tasks) = sync_update_panels(&this, update)?;
+            let fresh = contents
+                .iter()
+                .map(|(id, ..)| id.clone())
+                .collect::<Vec<_>>();
             let results = join_all(contents.into_iter().map(|(id, session, renderer, config)| {
                 let presentation = this.presentation.clone();
                 let workspace = this.workspace.clone();
@@ -1189,6 +1248,7 @@ impl PerspectiveViewerElement {
                         RestoreMode::Fresh,
                         config,
                         crate::tasks::RestoreErrors::Publish,
+                        missing,
                     )
                     .await?;
                     if workspace.is_master(&id) {
@@ -1201,6 +1261,7 @@ impl PerspectiveViewerElement {
             .await;
 
             results.into_iter().collect::<ApiResult<Vec<_>>>()?;
+            this.rerender_retained_overlays(&fresh).await?;
             join_all(eject_tasks)
                 .await
                 .into_iter()
@@ -1264,9 +1325,9 @@ impl PerspectiveViewerElement {
     /// });
     /// ```
     pub fn save(&self, options: Option<JsPanelOptions>) -> JsViewerConfigPromise {
-        let PanelOptions { panel: name } = parse_options(options);
         let this = self.clone();
         let fut = ApiFuture::new(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             this.workspace.effects().settle().await;
             let panel = this.resolve_panel(name)?;
             let viewer_config = panel
@@ -1300,9 +1361,12 @@ impl PerspectiveViewerElement {
         &self,
         options: Option<JsSaveWorkspaceOptions>,
     ) -> JsWorkspaceConfigPromise {
-        let SaveWorkspaceOptions { full_palette } = parse_options(options);
         let this = self.clone();
-        let fut = ApiFuture::new(Self::workspace_config(this, full_palette.unwrap_or(false)));
+        let fut = ApiFuture::new(async move {
+            let SaveWorkspaceOptions { full_palette } = parse_options(options)?;
+            Self::workspace_config(this, full_palette.unwrap_or(false)).await
+        });
+
         js_sys::Promise::from(fut).unchecked_into()
     }
 
@@ -1321,13 +1385,13 @@ impl PerspectiveViewerElement {
     /// })
     /// ```
     pub fn download(&self, options: Option<JsExportOptions>) -> ApiFuture<()> {
-        let ExportOptions {
-            method,
-            panel: name,
-        } = parse_options(options);
-        let method = method.map(|m| JsString::from(m.as_str()));
         let this = self.clone();
         ApiFuture::new_throttled(async move {
+            let ExportOptions {
+                method,
+                panel: name,
+            } = parse_options(options)?;
+            let method = method.map(|m| JsString::from(m.as_str()));
             let method = if let Some(method) = method
                 .map(|x| x.unchecked_into())
                 .map(serde_wasm_bindgen::from_value)
@@ -1368,13 +1432,14 @@ impl PerspectiveViewerElement {
     /// const data = await viewer.export("plugin");
     /// ```
     pub fn export(&self, options: Option<JsExportOptions>) -> ApiFuture<JsValue> {
-        let ExportOptions {
-            method,
-            panel: name,
-        } = parse_options(options);
-        let method = method.map(|m| JsString::from(m.as_str()));
         let this = self.clone();
         ApiFuture::new(async move {
+            let ExportOptions {
+                method,
+                panel: name,
+            } = parse_options(options)?;
+
+            let method = method.map(|m| JsString::from(m.as_str()));
             let method = if let Some(method) = method
                 .map(|x| x.unchecked_into())
                 .map(serde_wasm_bindgen::from_value)
@@ -1406,13 +1471,14 @@ impl PerspectiveViewerElement {
     /// })
     /// ```
     pub fn copy(&self, options: Option<JsExportOptions>) -> ApiFuture<()> {
-        let ExportOptions {
-            method,
-            panel: name,
-        } = parse_options(options);
-        let method = method.map(|m| JsString::from(m.as_str()));
         let this = self.clone();
         ApiFuture::new_throttled(async move {
+            let ExportOptions {
+                method,
+                panel: name,
+            } = parse_options(options)?;
+
+            let method = method.map(|m| JsString::from(m.as_str()));
             let method = if let Some(method) = method
                 .map(|x| x.unchecked_into())
                 .map(serde_wasm_bindgen::from_value)
@@ -1451,11 +1517,11 @@ impl PerspectiveViewerElement {
     /// await viewer.reset(true, {panel: "p1"});  // just "p1", + expressions
     /// ```
     pub fn reset(&self, reset_all: Option<bool>, options: Option<JsPanelOptions>) -> ApiFuture<()> {
-        let PanelOptions { panel: name } = parse_options(options);
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         let all = reset_all.unwrap_or_default();
         ApiFuture::new_throttled(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             let _effect = effect;
             let (completion, receiver) = Completion::new();
             {
@@ -1633,7 +1699,7 @@ impl PerspectiveViewerElement {
     /// region of the named panel, or the active panel when `panel` is omitted.
     #[wasm_bindgen]
     pub fn getSelection(&self, options: Option<JsPanelOptions>) -> ApiResult<Option<JsViewWindow>> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let panel = self.resolve_panel(name)?;
         Ok(panel.renderer.get_selection().map(|x| x.into()))
     }
@@ -1646,7 +1712,7 @@ impl PerspectiveViewerElement {
         window: Option<JsViewWindow>,
         options: Option<JsPanelOptions>,
     ) -> ApiResult<()> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let window = window.map(|x| x.into_serde_ext()).transpose()?;
         self.resolve_panel(name)?.renderer.set_selection(window);
         Ok(())
@@ -1657,7 +1723,7 @@ impl PerspectiveViewerElement {
     /// `panel` is omitted.
     #[wasm_bindgen]
     pub fn getEditPort(&self, options: Option<JsPanelOptions>) -> ApiResult<f64> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let panel = self.resolve_panel(name)?;
         let edit_port = if let Some(ctx) = panel.renderer.render_context() {
             ctx.edit_port
@@ -1873,13 +1939,25 @@ impl PerspectiveViewerElement {
     ///
     /// The element-level `settings` field does not exist on the argument
     /// type (it is shared across the element, not per-panel).
+    ///
+    /// # Arguments
+    ///
+    /// - `config` - The new panel's initial config, whose `table` is required.
+    /// - `options.wait_for_table` - when `true`, a `table` no loaded client
+    ///   hosts yet creates the panel empty and pending until the table is
+    ///   created, instead of the default rejection.
     #[wasm_bindgen]
-    pub fn addPanel(&self, config: JsViewerConfigInitial) -> ApiFuture<JsValue> {
+    pub fn addPanel(
+        &self,
+        config: JsViewerConfigInitial,
+        options: Option<JsAddPanelOptions>,
+    ) -> ApiFuture<JsValue> {
         clone!(self.elem, self.presentation, self.workspace);
         let effect = workspace.effects().guard();
         let notify = self.layout_changed_notify();
         ApiFuture::new(async move {
             let _effect = effect;
+            let AddPanelOptions { wait_for_table } = parse_options(options)?;
             let config = ViewerConfigInitial::decode(&config)?;
             let id = create_panel(
                 &elem,
@@ -1889,6 +1967,7 @@ impl PerspectiveViewerElement {
                 None,
                 config,
                 None,
+                MissingTable::from_wait(wait_for_table),
             )
             .await?;
             Ok(JsValue::from_str(id.as_str()))
@@ -1978,10 +2057,10 @@ impl PerspectiveViewerElement {
         column_name: String,
         options: Option<JsPanelOptions>,
     ) -> ApiFuture<()> {
-        let PanelOptions { panel: name } = parse_options(options);
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         ApiFuture::new_throttled(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             let _effect = effect;
             let panel = this.resolve_panel(name)?;
             let was_active = this.workspace.active_id().as_ref() == Some(&panel.id);