@perspective-dev/viewer 5.1.0 → 5.3.0

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,15 +39,45 @@ 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,
+    /// stamped on save and used to migrate older tokens. Callers do not
+    /// set it.
     pub version: V,
+
+    /// Per-column styling, keyed by column name. The viewer treats the
+    /// values as opaque — their shape is defined by the ACTIVE plugin,
+    /// so a config written for one plugin may carry keys another
+    /// ignores. Query the live shape with the `get_style_schema` agent
+    /// tool, or the plugin's `column_config_schema()`.
     pub columns_config: ColumnConfigMap,
+
+    /// Name of the visualization plugin, from the set registered on the
+    /// page (the `list_plugins` agent tool, or the plugin picker). This
+    /// also decides what the view fields MEAN visually: `columns` is
+    /// positional and each plugin reads the positions differently, and
+    /// `group_by`/`split_by` draw different things per plugin.
     pub plugin: String,
+
+    /// Plugin-wide settings (as opposed to the per-column
+    /// [`Self::columns_config`]). Opaque to the viewer and defined by
+    /// the active plugin; see `get_style_schema`.
     pub plugin_config: serde_json::Map<String, Value>,
-    pub table: Option<String>,
+
+    /// Name of the `Table` this panel renders, as hosted on the panel's
+    /// `Client`. Every placed panel has a table binding (creation
+    /// requires one by type — [`ViewerConfigInitial`]), so the saved
+    /// config carries it unconditionally.
+    pub table: String,
+
+    /// Selected theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid
+    /// names are the Perspective themes loaded on the page, which
+    /// `resetThemes()` re-scans. `None` selects the first available.
     pub theme: Option<String>,
+
+    /// Panel title, shown in its tab. `None` renders the default title.
     pub title: Option<String>,
 
     #[serde(flatten)]
@@ -93,41 +123,73 @@ impl Deref for PluginConfig {
 
 #[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize, TS)]
 pub struct ViewerConfigUpdate {
+    /// The `@perspective-dev/viewer` version a saved config was written
+    /// by, used to migrate older tokens. Omit it — the viewer stamps
+    /// the current version on save.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub version: VersionUpdate,
 
+    /// Name of the visualization plugin to switch to, from the set
+    /// registered on the page (the `list_plugins` agent tool, or the
+    /// plugin picker). Changing it changes what the view fields MEAN:
+    /// `columns` is positional and every plugin reads the positions
+    /// differently, and `group_by`/`split_by` draw different things per
+    /// plugin — so read the new plugin's roles before writing `columns`
+    /// for it.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub plugin: PluginUpdate,
 
+    /// Panel title, shown in its tab. `null` restores the default
+    /// title; omitting the field leaves the current one.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub title: TitleUpdate,
 
+    /// Name of the `Table` to render, as hosted on this panel's
+    /// `Client`. Rebinding an existing panel to another table keeps the
+    /// rest of the config, so column names that do not exist in the new
+    /// table will fail validation.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub table: TableUpdate,
 
+    /// Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
+    /// the Perspective themes loaded on the page, re-scanned by
+    /// `resetThemes()`. `null` selects the default.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub theme: ThemeUpdate,
 
+    /// Whether the settings sidebar is OPEN. Purely cosmetic chrome —
+    /// it does not affect what the viewer renders, and it is
+    /// element-level rather than per-panel.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub settings: SettingsUpdate,
 
+    /// Plugin-wide settings (as opposed to the per-column
+    /// [`Self::columns_config`]). The viewer passes these through
+    /// opaquely — their valid keys are defined by the ACTIVE plugin and
+    /// vary by plugin and by state, so query them with the
+    /// `get_style_schema` agent tool rather than guessing.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub plugin_config: PluginConfigUpdate,
 
+    /// Per-column styling — formatting, colors, and other per-column
+    /// controls — keyed by column name. Opaque to the viewer and
+    /// plugin-defined like [`Self::plugin_config`]; `get_style_schema`
+    /// reports the valid keys for a given column under the active
+    /// plugin.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
@@ -150,6 +212,157 @@ impl ViewerConfigUpdate {
     }
 }
 
+/// The initial configuration of a NEW panel (`addPanel`, `restore`'s
+/// panel-creating upsert, `restoreWorkspace` `panels` entries). Unlike
+/// [`ViewerConfigUpdate`] — a patch against existing state — creation has
+/// no prior state: `table` is REQUIRED (a placed panel without a table
+/// binding would be permanently blank), absent fields mean "default"
+/// rather than "leave unchanged" (so no [`OptionalUpdate`] tri-state), and
+/// there is no `settings` field (element-level, not per-panel).
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS)]
+pub struct ViewerConfigInitial {
+    /// Name of the `Table` the new panel renders, as hosted on the
+    /// `Client`. REQUIRED: a placed panel with no table binding would be
+    /// permanently blank.
+    pub table: String,
+
+    /// The `@perspective-dev/viewer` version a saved config was written
+    /// by. Omit it when creating a panel.
+    #[ts(optional)]
+    pub version: Option<String>,
+
+    /// Name of the visualization plugin, from the set registered on the
+    /// page (the `list_plugins` agent tool, or the plugin picker).
+    /// Decides what the view fields MEAN: `columns` is positional and
+    /// every plugin reads the positions differently, and
+    /// `group_by`/`split_by` draw different things per plugin. Absent
+    /// uses the default plugin.
+    #[ts(optional)]
+    pub plugin: Option<String>,
+
+    /// Panel title, shown in its tab. Absent renders the default title.
+    #[ts(optional)]
+    pub title: Option<String>,
+
+    /// Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
+    /// the Perspective themes loaded on the page. Absent uses the
+    /// default.
+    #[ts(optional)]
+    pub theme: Option<String>,
+
+    /// Plugin-wide settings (as opposed to the per-column
+    /// [`Self::columns_config`]). Opaque to the viewer and defined by
+    /// the ACTIVE plugin; query the valid keys with `get_style_schema`
+    /// rather than guessing.
+    #[ts(optional)]
+    pub plugin_config: Option<serde_json::Map<String, Value>>,
+
+    /// Per-column styling — formatting, colors, and other per-column
+    /// controls — keyed by column name. Plugin-defined like
+    /// [`Self::plugin_config`]; see `get_style_schema`.
+    #[ts(optional)]
+    pub columns_config: Option<ColumnConfigMap>,
+
+    #[serde(flatten)]
+    pub view_config: ViewConfigUpdate,
+}
+
+impl ViewerConfigInitial {
+    /// Decode a `JsValue` by auto-detecting format from JavaScript type.
+    pub fn decode(config: &JsValue) -> ApiResult<Self> {
+        Ok(config.into_serde_ext()?)
+    }
+
+    /// A default-config panel bound to `table` (the "New panel" menus).
+    /// Exhaustive on purpose — same drift alarm as the `From` impl below.
+    pub fn new(table: impl Into<String>) -> Self {
+        Self {
+            table: table.into(),
+            version: None,
+            plugin: None,
+            title: None,
+            theme: None,
+            plugin_config: None,
+            columns_config: None,
+            view_config: ViewConfigUpdate::default(),
+        }
+    }
+}
+
+fn up<T: Clone>(value: Option<T>) -> OptionalUpdate<T> {
+    match value {
+        Some(value) => OptionalUpdate::Update(value),
+        None => OptionalUpdate::Missing,
+    }
+}
+
+// Constructed EXHAUSTIVELY on purpose: a field added to
+// `ViewerConfigUpdate` breaks this impl at compile time, forcing the
+// "should creation carry it?" decision (the drift alarm).
+impl From<ViewerConfigInitial> for ViewerConfigUpdate {
+    fn from(value: ViewerConfigInitial) -> Self {
+        ViewerConfigUpdate {
+            version: up(value.version),
+            plugin: up(value.plugin),
+            title: up(value.title),
+            table: OptionalUpdate::Update(value.table),
+            theme: up(value.theme),
+            settings: OptionalUpdate::Missing,
+            plugin_config: up(value.plugin_config),
+            columns_config: up(value.columns_config),
+            view_config: value.view_config,
+        }
+    }
+}
+
+/// 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 {
         write!(

package/src/rust/config/workspace_config.rs

@@ -14,9 +14,9 @@ use std::collections::BTreeMap;
 
 use perspective_client::config::Filter;
 
-use crate::config::{PanelViewerConfig, ViewerConfigUpdate};
+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,13 +56,22 @@ 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
-/// [`PerspectiveViewerElement::restore`]. Mirrors [`WorkspaceConfig`],
-/// but `panels` entries are full [`ViewerConfigUpdate`]s so a stray per-panel
-/// `settings` can be detected (warned, then ignored — `create_panel` strips
-/// it).
+/// 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).
 #[derive(serde::Deserialize, ts_rs::TS)]
 pub struct WorkspaceConfigUpdate {
     #[serde(default)]
@@ -73,20 +82,139 @@ pub struct WorkspaceConfigUpdate {
     #[ts(optional)]
     pub layout: Option<crate::js::Layout>,
 
-    pub panels: BTreeMap<String, ViewerConfigUpdate>,
+    pub panels: 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).
     #[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"));
+    }
 }