@perspective-dev/viewer 5.2.0 → 5.3.0

package/src/rust/config/mod.rs

@@ -15,6 +15,7 @@
 
 mod column_config_schema;
 mod columns_config;
+mod css_scale;
 mod datetime_column_style;
 mod export_method;
 mod kvpair;
@@ -29,6 +30,7 @@ mod workspace_config;
 
 pub use column_config_schema::*;
 pub use columns_config::*;
+pub use css_scale::*;
 pub use datetime_column_style::*;
 pub use export_method::*;
 pub use number_series_style::*;

package/src/rust/config/options.rs

@@ -87,3 +87,13 @@ pub struct GetClientOptions {
     #[ts(optional)]
     pub panel: Option<String>,
 }
+
+/// Options for the `saveWorkspace()` method.
+#[derive(Deserialize, Default, TS)]
+pub struct SaveWorkspaceOptions {
+    /// When `true`, the emitted `palette` is the full set the element
+    /// holds rather than only the values the panels reference.
+    #[serde(default)]
+    #[ts(optional)]
+    pub full_palette: Option<bool>,
+}

package/src/rust/config/viewer_config.rs

@@ -24,7 +24,7 @@ use crate::renderer::ColumnConfigMap;
 
 /// The state of an entire `custom_elements::PerspectiveViewerElement` component
 /// and its `Plugin`: the element-level `settings` flag plus the per-panel
-/// [`PanelViewerConfig`]. The split exists so the whole-element config format
+/// [`PanelViewerConfig`]. The split exists so the workspace config format
 /// can serialize panel entries *without* a `settings` key (it is element-level
 /// state there, carried by the top-level `active` field instead), while the
 /// single-panel format flattens back to the legacy shape.
@@ -39,7 +39,7 @@ pub struct ViewerConfig<V: TS = String> {
 
 /// The per-panel state of a [`ViewerConfig`] — everything except the
 /// element-level `settings` flag. This is the `panels` entry type of the
-/// whole-element config format.
+/// workspace config format.
 #[derive(Debug, Default, Serialize, PartialEq, TS)]
 pub struct PanelViewerConfig<V: TS = String> {
     /// The `@perspective-dev/viewer` version that wrote this config,
@@ -315,15 +315,53 @@ impl From<ViewerConfigInitial> for ViewerConfigUpdate {
     }
 }
 
-// There is deliberately NO `TryFrom<ViewerConfigUpdate>` here. Requiring a
-// `table` is a property of the CREATION ENTRY POINTS — `addPanel`'s
-// argument type, `WorkspaceConfigUpdate::panels`, and the agent's
-// `add_panel` decode — each of which already has a `ViewerConfigInitial`
-// in hand. An update→initial conversion exists only to let a route holding
-// a PATCH pretend it is creating from scratch, which is how `restore`'s
-// upsert acquired the gate and started rejecting the table-less
-// restore-then-`load` contract. Its absence is what keeps that from
-// recurring: `create_panel` takes an update, so no caller needs one.
+/// The rejection every panel-creating route without a `table` resolves to.
+pub const CREATE_REQUIRES_TABLE: &str = "Cannot create a panel without a `table` — `load()` a \
+                                         `Client` and include `table` in the config, or use \
+                                         `addPanel()`";
+
+fn down<T: Clone>(value: OptionalUpdate<T>) -> Option<T> {
+    match value {
+        OptionalUpdate::Update(value) => Some(value),
+        OptionalUpdate::Missing | OptionalUpdate::SetDefault => None,
+    }
+}
+
+impl TryFrom<ViewerConfigUpdate> for ViewerConfigInitial {
+    type Error = ApiError;
+
+    fn try_from(value: ViewerConfigUpdate) -> Result<Self, Self::Error> {
+        // Exhaustive (no `..`) on purpose — the same drift alarm as the
+        // `From<ViewerConfigInitial>` impl above. `settings` is element-level
+        // state, stripped by `restore()` before resolution; discarded here.
+        let ViewerConfigUpdate {
+            version,
+            plugin,
+            title,
+            table,
+            theme,
+            settings: _settings,
+            plugin_config,
+            columns_config,
+            view_config,
+        } = value;
+
+        let OptionalUpdate::Update(table) = table else {
+            return Err(ApiError::new(CREATE_REQUIRES_TABLE));
+        };
+
+        Ok(Self {
+            table,
+            version: down(version),
+            plugin: down(plugin),
+            title: down(title),
+            theme: down(theme),
+            plugin_config: down(plugin_config),
+            columns_config: down(columns_config),
+            view_config,
+        })
+    }
+}
 
 impl std::fmt::Display for ViewerConfigUpdate {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
@@ -360,50 +398,6 @@ pub type VersionUpdate = OptionalUpdate<String>;
 pub type ColumnConfigUpdate = OptionalUpdate<ColumnConfigMap>;
 pub type PluginConfigUpdate = OptionalUpdate<serde_json::Map<String, Value>>;
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn initial_requires_a_table() {
-        let json = serde_json::json!({ "group_by": ["State"] });
-        let err = serde_json::from_value::<ViewerConfigInitial>(json).unwrap_err();
-        assert!(format!("{err}").contains("table"));
-    }
-
-    /// The creation → patch direction is the only one that exists (see the
-    /// note above the `From` impl); a `table` becomes a concrete update and
-    /// the element-level `settings` is not carried.
-    #[test]
-    fn initial_widens_to_an_update() {
-        let json = serde_json::json!({
-            "table": "superstore",
-            "plugin": "Datagrid",
-            "group_by": ["State"],
-        });
-
-        let initial: ViewerConfigInitial = serde_json::from_value(json).unwrap();
-        let update = ViewerConfigUpdate::from(initial);
-        assert!(matches!(&update.table, OptionalUpdate::Update(x) if x == "superstore"));
-        assert!(matches!(&update.settings, OptionalUpdate::Missing));
-        assert!(matches!(&update.plugin, OptionalUpdate::Update(x) if x == "Datagrid"));
-        assert_eq!(
-            update.view_config.group_by.as_deref(),
-            Some(&["State".to_owned()][..])
-        );
-    }
-
-    /// A table-less patch is a legitimate creation input now that
-    /// `create_panel` takes an update — the deferred panel a `load()`
-    /// binds. Nothing in this module may reject it.
-    #[test]
-    fn a_table_less_update_is_representable() {
-        let json = serde_json::json!({ "group_by": ["State"] });
-        let update: ViewerConfigUpdate = serde_json::from_value(json).unwrap();
-        assert!(matches!(&update.table, OptionalUpdate::Missing));
-    }
-}
-
 /// Handles `{}` when included as a field with `#[serde(default)]`.
 impl<T: Clone> Default for OptionalUpdate<T> {
     fn default() -> Self {

package/src/rust/config/workspace_config.rs

@@ -14,9 +14,9 @@ use std::collections::BTreeMap;
 
 use perspective_client::config::Filter;
 
-use crate::config::{PanelViewerConfig, ViewerConfigInitial};
+use crate::config::{CssKind, PanelViewerConfig, ViewerConfigInitial};
 
-/// The whole-element config format (`{version, active?, layout, panels}`) —
+/// The workspace config format (`{version, active?, layout, panels}`) —
 /// the multi-panel counterpart of the single-panel [`ViewerConfig`] — as
 /// emitted by [`PerspectiveViewerElement::save`].
 ///
@@ -56,9 +56,17 @@ pub struct WorkspaceConfig {
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub masters: Vec<String>,
+
+    /// Named color-scale definitions shared by every panel: CSS custom
+    /// property name (`--psp-user--<kind>-<name>`) → canonical CSS
+    /// value.
+    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub palette: BTreeMap<String, String>,
 }
 
-/// The parse target of a whole-element config in
+/// 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
@@ -79,15 +87,134 @@ pub struct WorkspaceConfigUpdate {
     /// 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).
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
-    pub global_filters: Vec<Filter>,
+    pub global_filters: Option<Vec<Filter>>,
 
     /// The master (filter-source) panels, by saved `panels` key. An id not in
     /// `panels` warns and is dropped.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
-    pub masters: Vec<String>,
+    pub masters: Option<Vec<String>>,
+
+    /// Named color-scale definitions to apply to the host (see
+    /// [`WorkspaceConfig::palette`]), replacing any previously restored
+    /// palette.
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub palette: Option<BTreeMap<String, String>>,
+}
+
+/// Validate a restored palette map: each key's `--psp-user--<kind>-`
+/// prefix selects the reader that canonicalizes its value.
+pub fn validate_palette(
+    palette: BTreeMap<String, String>,
+) -> Result<BTreeMap<String, String>, String> {
+    palette
+        .into_iter()
+        .map(|(name, value)| {
+            let kind = CssKind::of_var(&name).ok_or_else(|| {
+                format!(
+                    "`palette` key `{name}` must start with `--psp-user--gradient-`, \
+                     `--psp-user--palette-` or `--psp-user--color-`"
+                )
+            })?;
+
+            let canonical = kind
+                .canonicalize(&value)
+                .map_err(|error| format!("`palette[\"{name}\"]`: {error}"))?;
+
+            Ok((name, canonical))
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn palette_serializes_only_when_present() {
+        let config = WorkspaceConfig {
+            version: "x".to_owned(),
+            active: None,
+            layout: None,
+            panels: BTreeMap::new(),
+            global_filters: vec![],
+            masters: vec![],
+            palette: BTreeMap::new(),
+        };
+
+        assert_eq!(
+            serde_json::to_value(&config).unwrap(),
+            json!({ "version": "x", "layout": null, "panels": {} })
+        );
+
+        let mut palette = BTreeMap::new();
+        palette.insert("--psp-user--color-hot".to_owned(), "#ff0000".to_owned());
+
+        let config = WorkspaceConfig { palette, ..config };
+        assert_eq!(
+            serde_json::to_value(&config).unwrap(),
+            json!({
+                "version": "x",
+                "layout": null,
+                "panels": {},
+                "palette": { "--psp-user--color-hot": "#ff0000" },
+            })
+        );
+    }
+
+    #[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());
+
+        let update: WorkspaceConfigUpdate = serde_json::from_value(json!({
+            "panels": {},
+            "palette": {
+                "--psp-user--gradient-1": "linear-gradient(#000, #fff)",
+                "--psp-user--palette-warm": "linear-gradient(90deg, RGB(255,0,0), #ff0)",
+                "--psp-user--color-hot": "#F00",
+            },
+        }))
+        .unwrap();
+
+        let valid = validate_palette(update.palette.unwrap()).unwrap();
+        assert_eq!(
+            valid.get("--psp-user--gradient-1").unwrap(),
+            "linear-gradient(to right, #000000 0%, #ffffff 100%)"
+        );
+        assert_eq!(
+            valid.get("--psp-user--palette-warm").unwrap(),
+            "linear-gradient(to right, #ff0000, #ffff00)"
+        );
+        assert_eq!(valid.get("--psp-user--color-hot").unwrap(), "#ff0000");
+
+        let bad = |name: &str, value: &str| {
+            let mut map = BTreeMap::new();
+            map.insert(name.to_owned(), value.to_owned());
+            validate_palette(map).unwrap_err()
+        };
+
+        assert!(bad("--psp-user--other-1", "#ff0000").contains("--psp-user--other-1"));
+        assert!(bad("--psp-charts--gradient", "#ff0000").contains("must start with"));
+        assert!(
+            bad(
+                "--psp-user--palette-1",
+                "linear-gradient(#000 0%, #fff 100%)"
+            )
+            .contains("--psp-user--palette-1")
+        );
+        assert!(bad("--psp-user--gradient-1", "#ff0000").contains("linear-gradient"));
+        assert!(bad("--psp-user--color-1", "red").contains("red"));
+    }
 }