@perspective-dev/viewer 5.5.0 → 5.6.0

package/src/rust/config/viewer_config.rs

@@ -20,6 +20,7 @@ use serde_json::Value;
 use ts_rs::TS;
 use wasm_bindgen::prelude::*;
 
+use crate::config::TableRef;
 use crate::renderer::ColumnConfigMap;
 
 /// The state of an entire `custom_elements::PerspectiveViewerElement` component
@@ -30,18 +31,18 @@ use crate::renderer::ColumnConfigMap;
 /// single-panel format flattens back to the legacy shape.
 #[derive(Debug, Default, Serialize, PartialEq, TS)]
 #[serde(deny_unknown_fields)]
-pub struct ViewerConfig<V: TS = String> {
+pub struct ViewerConfig<V: TS = String, T: TS = TableRef> {
     pub settings: bool,
 
     #[serde(flatten)]
-    pub panel: PanelViewerConfig<V>,
+    pub panel: PanelViewerConfig<V, T>,
 }
 
 /// The per-panel state of a [`ViewerConfig`] — everything except the
 /// element-level `settings` flag. This is the `panels` entry type of the
 /// workspace config format.
 #[derive(Debug, Default, Serialize, PartialEq, TS)]
-pub struct PanelViewerConfig<V: TS = String> {
+pub struct PanelViewerConfig<V: TS = String, T: TS = TableRef> {
     /// The `@perspective-dev/viewer` version that wrote this config,
     /// stamped on save and used to migrate older tokens. Callers do not
     /// set it.
@@ -66,11 +67,11 @@ pub struct PanelViewerConfig<V: TS = String> {
     /// the active plugin; see `get_style_schema`.
     pub plugin_config: serde_json::Map<String, Value>,
 
-    /// 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,
+    /// The `Table` this panel renders: its hosted name in a
+    /// [`WorkspaceConfig`] `panels` entry (`T = String`), and a
+    /// [`TableRef`] — a name, or a recursively inlined derived-table
+    /// definition — in the single-panel `save()` format.
+    pub table: T,
 
     /// Selected theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid
     /// names are the Perspective themes loaded on the page, which
@@ -84,14 +85,40 @@ pub struct PanelViewerConfig<V: TS = String> {
     pub view_config: ViewConfig,
 }
 
-impl<V: TS> Deref for ViewerConfig<V> {
-    type Target = PanelViewerConfig<V>;
+impl<V: TS, T: TS> Deref for ViewerConfig<V, T> {
+    type Target = PanelViewerConfig<V, T>;
 
     fn deref(&self) -> &Self::Target {
         &self.panel
     }
 }
 
+impl<V: TS, T: TS> PanelViewerConfig<V, T> {
+    /// The same config with the `table` slot mapped, which is how the
+    /// single-panel emitters convert a bound name to its inline form.
+    pub fn map_table<U: TS>(self, f: impl FnOnce(T) -> U) -> PanelViewerConfig<V, U> {
+        PanelViewerConfig {
+            version: self.version,
+            columns_config: self.columns_config,
+            plugin: self.plugin,
+            plugin_config: self.plugin_config,
+            table: f(self.table),
+            theme: self.theme,
+            title: self.title,
+            view_config: self.view_config,
+        }
+    }
+}
+
+impl<V: TS, T: TS> ViewerConfig<V, T> {
+    pub fn map_table<U: TS>(self, f: impl FnOnce(T) -> U) -> ViewerConfig<V, U> {
+        ViewerConfig {
+            settings: self.settings,
+            panel: self.panel.map_table(f),
+        }
+    }
+}
+
 pub static API_VERSION: LazyLock<&'static str> = LazyLock::new(|| {
     #[derive(Deserialize)]
     struct Package {
@@ -102,7 +129,7 @@ pub static API_VERSION: LazyLock<&'static str> = LazyLock::new(|| {
     pkg.version
 });
 
-impl ViewerConfig {
+impl<V: TS + Serialize, T: TS + Serialize> ViewerConfig<V, T> {
     /// Encode a `ViewerConfig` to a `JsValue` in a supported type.
     pub fn encode(&self) -> ApiResult<JsValue> {
         Ok(JsValue::from_serde_ext(self)?)
@@ -150,10 +177,11 @@ pub struct ViewerConfigUpdate {
     #[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.
+    /// The `Table` to render: a name as hosted on this panel's `Client`,
+    /// or an inline derived-table definition to materialize (reusing a
+    /// structurally identical derived `Table` when one exists). Rebinding
+    /// an existing panel 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)]
@@ -305,7 +333,7 @@ impl From<ViewerConfigInitial> for ViewerConfigUpdate {
             version: up(value.version),
             plugin: up(value.plugin),
             title: up(value.title),
-            table: OptionalUpdate::Update(value.table),
+            table: OptionalUpdate::Update(value.table.into()),
             theme: up(value.theme),
             settings: OptionalUpdate::Missing,
             plugin_config: up(value.plugin_config),
@@ -350,6 +378,8 @@ impl TryFrom<ViewerConfigUpdate> for ViewerConfigInitial {
             return Err(ApiError::new(CREATE_REQUIRES_TABLE));
         };
 
+        let table = table.name()?.to_owned();
+
         Ok(Self {
             table,
             version: down(version),
@@ -393,7 +423,7 @@ pub type PluginUpdate = OptionalUpdate<String>;
 pub type SettingsUpdate = OptionalUpdate<bool>;
 pub type ThemeUpdate = OptionalUpdate<String>;
 pub type TitleUpdate = OptionalUpdate<String>;
-pub type TableUpdate = OptionalUpdate<String>;
+pub type TableUpdate = OptionalUpdate<TableRef>;
 pub type VersionUpdate = OptionalUpdate<String>;
 pub type ColumnConfigUpdate = OptionalUpdate<ColumnConfigMap>;
 pub type PluginConfigUpdate = OptionalUpdate<serde_json::Map<String, Value>>;

package/src/rust/config/workspace_config.rs

@@ -12,11 +12,153 @@
 
 use std::collections::BTreeMap;
 
-use perspective_client::config::Filter;
+use perspective_client::config::{Filter, ViewConfig};
 
 use crate::config::{OptionalUpdate, PanelViewerConfig, ViewerConfigInitial};
 use crate::utils::CssKind;
 
+/// A derived `Table`'s definition: the `Table` its source `View` reads, and
+/// the config of that `View`; generic over the `table` slot, which is a name
+/// in the workspace `derived_tables` map and a recursive [`TableRef`] when
+/// inlined in a single-panel config.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize, ts_rs::TS)]
+pub struct DerivedTableConfig<T: ts_rs::TS = String> {
+    /// The `Table` this derivation reads, which may itself be another
+    /// derived `Table`.
+    pub table: T,
+
+    #[serde(flatten)]
+    pub view_config: ViewConfig,
+}
+
+/// What may occupy a `table` position in a single-panel config: a hosted
+/// `Table`'s name, or an inline derived-table definition recursing through
+/// its own `table` field until a concrete name.
+#[derive(Clone, Debug, PartialEq, serde::Serialize)]
+#[serde(untagged)]
+pub enum TableRef {
+    Name(String),
+    Derived(Box<DerivedTableConfig<TableRef>>),
+}
+
+/// Hand-written because the derived decl's recursion sits in a generic alias
+/// instantiation (`DerivedTableConfig<TableRef>`), which TypeScript expands
+/// eagerly and rejects as circular; recursion is legal only deferred through
+/// an object-literal node.
+impl ts_rs::TS for TableRef {
+    type OptionInnerType = Self;
+    type WithoutGenerics = Self;
+
+    fn docs() -> Option<String> {
+        Some(
+            "/**\n * What may occupy a `table` position in a single-panel config: a hosted\n * \
+             `Table`'s name, or an inline derived-table definition recursing through\n * its own \
+             `table` field until a concrete name.\n */\n"
+                .to_owned(),
+        )
+    }
+
+    fn name() -> String {
+        "TableRef".to_owned()
+    }
+
+    fn decl() -> String {
+        format!(
+            "type TableRef = string | (Omit<{}, \"table\"> & {{ table: TableRef }});",
+            <DerivedTableConfig as ts_rs::TS>::ident()
+        )
+    }
+
+    fn decl_concrete() -> String {
+        <Self as ts_rs::TS>::decl()
+    }
+
+    fn inline() -> String {
+        format!(
+            "string | (Omit<{}, \"table\"> & {{ table: TableRef }})",
+            <DerivedTableConfig as ts_rs::TS>::ident()
+        )
+    }
+
+    fn inline_flattened() -> String {
+        panic!("`TableRef` cannot be flattened")
+    }
+
+    fn visit_dependencies(visitor: &mut impl ts_rs::TypeVisitor)
+    where
+        Self: 'static,
+    {
+        visitor.visit::<DerivedTableConfig>();
+    }
+
+    fn output_path() -> Option<std::path::PathBuf> {
+        Some(std::path::PathBuf::from("TableRef.ts"))
+    }
+}
+
+impl Default for TableRef {
+    fn default() -> Self {
+        Self::Name(String::default())
+    }
+}
+
+impl From<String> for TableRef {
+    fn from(value: String) -> Self {
+        Self::Name(value)
+    }
+}
+
+impl TableRef {
+    /// The concrete `Table` name, or an error for an inline definition which
+    /// a restore boundary has not resolved.
+    pub fn name(&self) -> Result<&str, perspective_js::utils::ApiError> {
+        match self {
+            Self::Name(name) => Ok(name),
+            Self::Derived(_) => Err(perspective_js::utils::ApiError::new(
+                "Unresolved inline derived table",
+            )),
+        }
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for TableRef {
+    /// Hand-written (not `untagged`) so a malformed inline definition
+    /// reports its own error instead of "data did not match any variant".
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        struct TableRefVisitor;
+        impl<'de> serde::de::Visitor<'de> for TableRefVisitor {
+            type Value = TableRef;
+
+            fn expecting(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                fmt.write_str("a table name or an inline derived table definition")
+            }
+
+            fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
+            where
+                E: serde::de::Error,
+            {
+                Ok(TableRef::Name(value.to_owned()))
+            }
+
+            fn visit_map<A>(self, map: A) -> Result<Self::Value, A::Error>
+            where
+                A: serde::de::MapAccess<'de>,
+            {
+                let config = <DerivedTableConfig<TableRef> as serde::Deserialize>::deserialize(
+                    serde::de::value::MapAccessDeserializer::new(map),
+                )?;
+
+                Ok(TableRef::Derived(Box::new(config)))
+            }
+        }
+
+        deserializer.deserialize_any(TableRefVisitor)
+    }
+}
+
 /// The workspace config format (`{version, active?, layout, panels}`) —
 /// the multi-panel counterpart of the single-panel [`ViewerConfig`] — as
 /// emitted by [`PerspectiveViewerElement::save`].
@@ -39,7 +181,14 @@ pub struct WorkspaceConfig {
     /// DETERMINISTIC (sorted) key order — a fresh `HashMap` per call
     /// iterates in a per-instance random order, which made consecutive
     /// `save()` outputs byte-unstable.
-    pub panels: BTreeMap<String, PanelViewerConfig>,
+    pub panels: BTreeMap<String, PanelViewerConfig<String, String>>,
+
+    /// Named derived `Table`s, each a `View` of its `parent` promoted to a
+    /// `Table`. A `BTreeMap` for the same determinism reason as `panels`.
+    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub derived_tables: BTreeMap<String, DerivedTableConfig>,
 
     /// The element-level global (master/detail cross-) filters. A transient
     /// overlay on every detail panel's view — persisted here, never in a
@@ -92,6 +241,13 @@ pub struct WorkspaceConfigUpdate {
     #[ts(optional)]
     pub panels: Option<BTreeMap<String, ViewerConfigInitial>>,
 
+    /// The complete replacement set of derived `Table`s, in any order (they
+    /// are built parent-first); absent keeps the current ones, `{}` deletes
+    /// them all.
+    #[serde(default)]
+    #[ts(optional)]
+    pub derived_tables: Option<BTreeMap<String, DerivedTableConfig>>,
+
     /// The element-level cross-filter set applied to every detail panel as
     /// one unattributed bucket, replacing the current set; `null` clears it.
     #[serde(default)]
@@ -138,129 +294,3 @@ pub fn validate_palette(
         })
         .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_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_eq!(update.palette, OptionalUpdate::Missing);
-
-        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 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%)"
-        );
-        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"));
-    }
-}