@perspective-dev/viewer 5.3.1 → 5.5.0

package/src/rust/config/options.rs

@@ -44,6 +44,28 @@ pub struct RestoreOptions {
     /// known-good config to recover exactly.
     #[ts(optional)]
     pub suppress_errors: Option<bool>,
+
+    /// 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.
+    #[ts(optional)]
+    pub wait_for_table: Option<bool>,
+}
+
+/// Options for the `restoreWorkspace()` method.
+#[derive(Deserialize, Default, TS)]
+pub struct RestoreWorkspaceOptions {
+    /// As `RestoreOptions::wait_for_table`, applied to every panel entry.
+    #[ts(optional)]
+    pub wait_for_table: Option<bool>,
+}
+
+/// Options for the `addPanel()` method.
+#[derive(Deserialize, Default, TS)]
+pub struct AddPanelOptions {
+    /// As `RestoreOptions::wait_for_table`.
+    #[ts(optional)]
+    pub wait_for_table: Option<bool>,
 }
 
 /// The `eject` argument: the loaded client to remove by name; the active
@@ -77,6 +99,34 @@ pub struct GetTableOptions {
     pub panel: Option<String>,
 }
 
+/// How `getView` resolves the `View` it returns.
+#[derive(Clone, Copy, Default, Deserialize, PartialEq, Eq, TS)]
+#[serde(rename_all = "lowercase")]
+pub enum GetViewMode {
+    /// The panel's own bound `View`, which the viewer replaces on config
+    /// change and deletes on auto-pause or `delete()`; rejects when none is
+    /// bound.
+    #[default]
+    Live,
+
+    /// A caller-owned `View` built from the panel's effective config,
+    /// independent of the render lifecycle.
+    Clone,
+
+    /// `live` when the panel has a bound `View`, else `clone`.
+    Auto,
+}
+
+/// The `getView` argument: the `mode` and the target panel.
+#[derive(Deserialize, Default, TS)]
+pub struct GetViewOptions {
+    #[ts(optional)]
+    pub mode: Option<GetViewMode>,
+
+    #[ts(optional)]
+    pub panel: Option<String>,
+}
+
 /// The `getClient` argument: whether to `wait` for a `Client`, and the target
 /// panel.
 #[derive(Deserialize, Default, TS)]

package/src/rust/config/workspace_config.rs

@@ -14,7 +14,8 @@ use std::collections::BTreeMap;
 
 use perspective_client::config::Filter;
 
-use crate::config::{CssKind, PanelViewerConfig, ViewerConfigInitial};
+use crate::config::{OptionalUpdate, PanelViewerConfig, ViewerConfigInitial};
+use crate::utils::CssKind;
 
 /// The workspace config format (`{version, active?, layout, panels}`) —
 /// the multi-panel counterpart of the single-panel [`ViewerConfig`] — as
@@ -66,48 +67,52 @@ pub struct WorkspaceConfig {
     pub palette: BTreeMap<String, String>,
 }
 
-/// The parse target of a workspace config in
-/// [`PerspectiveViewerElement::restoreWorkspace`]. Mirrors
-/// [`WorkspaceConfig`], but `panels` entries are [`ViewerConfigInitial`]s —
-/// every entry creates a NEW panel, so `table` is required by type (a
-/// stray per-panel `settings` key is ignored; it is element-level state,
-/// carried by the top-level `active` field).
+/// The [`PerspectiveViewerElement::restoreWorkspace`] argument: a field-wise
+/// update of the element's workspace state, like [`ViewerConfigUpdate`] for a
+/// panel, where an absent key is unchanged, `null` resets and a value
+/// replaces.
 #[derive(serde::Deserialize, ts_rs::TS)]
 pub struct WorkspaceConfigUpdate {
+    /// The panel to activate with the settings sidebar open, by `panels` key
+    /// or existing panel id; `null` closes the sidebar.
     #[serde(default)]
+    #[ts(as = "Option<_>")]
     #[ts(optional)]
-    pub active: Option<String>,
+    pub active: OptionalUpdate<String>,
 
+    /// The layout tree to stage, naming `panels` keys or existing panel ids.
     #[serde(default)]
     #[ts(optional)]
     pub layout: Option<crate::js::Layout>,
 
-    pub panels: BTreeMap<String, ViewerConfigInitial>,
+    /// The complete replacement panel set, each [`ViewerConfigInitial`] entry
+    /// creating a new panel (`{}` empties the element); absent keeps the
+    /// existing panels.
+    #[serde(default)]
+    #[ts(optional)]
+    pub panels: Option<BTreeMap<String, ViewerConfigInitial>>,
 
-    /// The element-level global (master/detail cross-) filters to re-apply as
-    /// a transient overlay on every DETAIL panel. Restored as one
-    /// unattributed bucket: the next selection on any master replaces it.
-    /// `Option` so an explicit `undefined` property deserializes as
-    /// `None` like an absent key (also `masters` / `palette` below).
+    /// The element-level cross-filter set applied to every detail panel as
+    /// one unattributed bucket, replacing the current set; `null` clears it.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
-    pub global_filters: Option<Vec<Filter>>,
+    pub global_filters: OptionalUpdate<Vec<Filter>>,
 
-    /// The master (filter-source) panels, by saved `panels` key. An id not in
-    /// `panels` warns and is dropped.
+    /// The master (filter-source) panels by `panels` key or existing panel
+    /// id, unknown ids dropped with a warning; `null` demotes every panel.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
-    pub masters: Option<Vec<String>>,
+    pub masters: OptionalUpdate<Vec<String>>,
 
-    /// Named color-scale definitions to apply to the host (see
-    /// [`WorkspaceConfig::palette`]), replacing any previously restored
-    /// palette.
+    /// Named color-scale definitions applied to the host (see
+    /// [`WorkspaceConfig::palette`]), replacing the previous palette; `null`
+    /// clears it.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
-    pub palette: Option<BTreeMap<String, String>>,
+    pub palette: OptionalUpdate<BTreeMap<String, String>>,
 }
 
 /// Validate a restored palette map: each key's `--psp-user--<kind>-`
@@ -172,11 +177,48 @@ mod tests {
         );
     }
 
+    #[test]
+    fn update_absent_fields_are_missing_and_null_resets() {
+        let update: WorkspaceConfigUpdate = serde_json::from_value(json!({})).unwrap();
+        assert!(update.panels.is_none());
+        assert!(update.layout.is_none());
+        assert_eq!(update.active, OptionalUpdate::Missing);
+        assert_eq!(update.global_filters, OptionalUpdate::Missing);
+        assert_eq!(update.masters, OptionalUpdate::Missing);
+        assert_eq!(update.palette, OptionalUpdate::Missing);
+
+        let update: WorkspaceConfigUpdate = serde_json::from_value(json!({
+            "panels": null,
+            "active": null,
+            "global_filters": null,
+            "masters": null,
+            "palette": null,
+        }))
+        .unwrap();
+
+        assert!(update.panels.is_none());
+        assert_eq!(update.active, OptionalUpdate::SetDefault);
+        assert_eq!(update.global_filters, OptionalUpdate::SetDefault);
+        assert_eq!(update.masters, OptionalUpdate::SetDefault);
+        assert_eq!(update.palette, OptionalUpdate::SetDefault);
+
+        let update: WorkspaceConfigUpdate = serde_json::from_value(json!({
+            "panels": {},
+            "global_filters": [["Region", "==", "West"]],
+            "masters": ["a"],
+        }))
+        .unwrap();
+
+        assert_eq!(update.panels.map(|p| p.len()), Some(0));
+        assert_eq!(update.masters, OptionalUpdate::Update(vec!["a".to_owned()]));
+        assert!(matches!(update.global_filters, OptionalUpdate::Update(ref f) if f.len() == 1));
+    }
+
     #[test]
     fn update_palette_defaults_empty_and_validates_by_prefix() {
         let update: WorkspaceConfigUpdate =
             serde_json::from_value(json!({ "panels": {} })).unwrap();
-        assert!(update.palette.is_none());
+        assert_eq!(update.palette, OptionalUpdate::Missing);
 
         let update: WorkspaceConfigUpdate = serde_json::from_value(json!({
             "panels": {},
@@ -188,7 +230,11 @@ mod tests {
         }))
         .unwrap();
 
-        let valid = validate_palette(update.palette.unwrap()).unwrap();
+        let OptionalUpdate::Update(palette) = update.palette else {
+            panic!("palette missing");
+        };
+
+        let valid = validate_palette(palette).unwrap();
         assert_eq!(
             valid.get("--psp-user--gradient-1").unwrap(),
             "linear-gradient(to right, #000000 0%, #ffffff 100%)"

package/src/rust/custom_elements/debug_plugin.rs

@@ -66,16 +66,7 @@ impl PerspectiveDebugPluginElement {
     }
 
     /// Delegates to `draw()` VIRTUALLY — through the JS element's `draw`
-    /// property, never `self.draw(view)` (Rust static dispatch). This
-    /// element is the documented base class for custom plugins
-    /// (`class MyPlugin extends
-    /// customElements.get("perspective-viewer-plugin")`), whose contract is
-    /// "`update()` defaults to dispatch to `draw()`" — a
-    /// subclass overriding only `draw` must receive `update`-path repaints
-    /// (`BindDisposition::Unchanged`/`Adopted` runs,
-    /// `PLUGIN_DRAW_INVARIANT_PLAN.md`); the static call bypassed the
-    /// override and repainted the Debug CSV instead (the
-    /// `view_lifecycle.spec` regression).
+    /// property, never `self.draw(view)` (Rust static dispatch).
     pub fn update(&self, view: &perspective_js::View) -> ApiFuture<()> {
         clone!(self.elem, view);
         ApiFuture::new(async move {

package/src/rust/custom_elements/mod.rs

@@ -13,8 +13,5 @@
 //! Each file in `custom_elements` exports a single struct which will be the
 //! public [`wasm_bindgen`] API to a JavaScript Custom Element.
 
-pub mod copy_dropdown;
 pub mod debug_plugin;
-pub mod export_dropdown;
-pub mod modal;
 pub mod viewer;