@perspective-dev/viewer 5.2.0 → 5.3.1

package/src/rust/components/viewer.rs

@@ -166,7 +166,7 @@ impl Component for PerspectiveViewer {
         let renderer_props = active_renderer.to_props(None);
         let presentation_props = ctx.props().presentation.to_props(PtrEqRc::new(vec![]));
         let on_close_column_settings = ctx.link().callback(|_| OpenColumnSettings {
-            locator: None,
+            target: None,
             sender: None,
             toggle: false,
         });
@@ -319,8 +319,8 @@ impl Component for PerspectiveViewer {
             ClearGlobalFilters => self.on_clear_global_filters(ctx),
 
             // Settings sidebar + divider pump + column settings (`settings.rs`)
-            ToggleSettingsInit(update, resolve) => {
-                self.on_toggle_settings_init(ctx, update, resolve)
+            ToggleSettingsInit(update, announce, resolve) => {
+                self.on_toggle_settings_init(ctx, update, announce, resolve)
             },
             ToggleSettingsComplete(update, resolve) => {
                 self.on_toggle_settings_complete(ctx, update, resolve)
@@ -333,25 +333,29 @@ impl Component for PerspectiveViewer {
             SettingsPanelTabChanged(tab) => self.on_settings_panel_tab_changed(tab),
             SettingsPanelAutoWidth(w) => self.on_settings_panel_auto_width(w),
             OpenColumnSettings {
-                locator,
+                target,
                 sender,
                 toggle,
-            } => self.on_open_column_settings(ctx, locator, sender, toggle),
+            } => self.on_open_column_settings(ctx, target, sender, toggle),
             ColumnSettingsPanelSizeUpdate(x) => self.on_column_settings_panel_size_update(x),
             ColumnSettingsPanelAutoWidth(w) => self.on_column_settings_panel_auto_width(w),
-            ToggleColumnSettingsPin => self.on_toggle_column_settings_pin(),
+            ToggleColumnSettingsPin => self.on_toggle_column_settings_pin(ctx),
+            ToggleColumnSettingsPinComplete(resolve) => {
+                self.on_toggle_column_settings_pin_complete(resolve)
+            },
             ColumnSettingsTabChanged(tab) => self.on_column_settings_tab_changed(ctx, tab),
             ToggleDebug => self.on_toggle_debug(ctx),
 
             // Value-semantic snapshot plumbing (`snapshots.rs`)
-            UpdateSession(props) => self.on_update_session(*props),
+            UpdateSession(props) => self.on_update_session(ctx, *props),
             UpdateSessionStats(stats, has_table) => self.on_update_session_stats(stats, has_table),
             UpdateGlobalFilters => self.on_update_global_filters(ctx),
             UpdateRenderer(props) => self.on_update_renderer(*props),
             UpdatePresentation(props) => self.on_update_presentation(ctx, *props),
             UpdateSettingsOpen(open) => self.on_update_settings_open(open),
             UpdateIsWorkspace(is_workspace) => self.on_update_is_workspace(is_workspace),
-            UpdateColumnSettings(ocs) => self.on_update_column_settings(*ocs),
+            UpdateColumnSettings(ocs) => self.on_update_column_settings(ctx, *ocs),
+            UpdateColumnSettingsCommit(resolve) => self.on_update_column_settings_commit(resolve),
             UpdateDragDrop(props) => self.on_update_dragdrop(*props),
             UpdateInFlight(count) => self.on_update_in_flight(count),
         }

package/src/rust/config/column_config_schema.rs

@@ -15,18 +15,15 @@ use std::collections::HashSet;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
-use super::{KeyValueOpts, NumberSeriesStyleDefaultConfig};
+use super::{
+    CssKind, CustomNumberFormatConfig, DatetimeFormatType, KeyValueOpts,
+    NumberSeriesStyleDefaultConfig,
+};
 
 /// The full schema for one column at one point in time. Plugins may return
 /// different schemas for the same column based on the column's current
 /// stored value (e.g. to hide dependent fields), so this is re-queried on
 /// every field update.
-///
-/// Each entry is a [`ControlSpec`]. Primitive variants carry their own
-/// `key` (JSON storage key) inline; the sidebar UI label is supplied by
-/// CSS via `--psp-label--<key>--content`. Composite variants render a
-/// self-contained Yew component that supplies its own labels and owns a
-/// fixed key namespace via [`ControlSpec::serialized_keys`].
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct ColumnConfigSchema {
     pub fields: Vec<ControlSpec>,
@@ -47,6 +44,21 @@ impl ColumnConfigSchema {
         }
         out
     }
+
+    pub fn leaf_fields(&self) -> Vec<&ControlSpec> {
+        fn collect<'a>(fields: &'a [ControlSpec], out: &mut Vec<&'a ControlSpec>) {
+            for spec in fields {
+                match spec {
+                    ControlSpec::Group { fields, .. } => collect(fields, out),
+                    leaf => out.push(leaf),
+                }
+            }
+        }
+
+        let mut out = vec![];
+        collect(&self.fields, &mut out);
+        out
+    }
 }
 
 /// Discriminated union of widget kinds the viewer can render. Composite
@@ -93,33 +105,26 @@ pub enum ControlSpec {
         key: String,
         default: String,
     },
-    /// Paired pos/neg color picker rendered as a single horizontal
-    /// gradient/range bar. Used to expose the existing
-    /// [`crate::components::form::color_range_selector::ColorRangeSelector`]
-    /// widget at primitive granularity. Owns two top-level keys
-    /// (`key_pos` + `key_neg`); the visible label is derived from
-    /// `key_pos`.
-    ColorRange {
-        key_pos: String,
-        key_neg: String,
-        default_pos: String,
-        default_neg: String,
-        /// When `true`, the bar renders as a continuous gradient
-        /// (e.g. for `gradient` color modes); when `false`, the bar
-        /// renders as a hard pos/neg split. Currently only changes the
-        /// visual; pos/neg semantics are unchanged.
-        #[serde(default)]
-        is_gradient: bool,
+    Palette {
+        key: String,
+        default: String,
+
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        max: Option<usize>,
     },
+    GradientStops {
+        key: String,
+        default: String,
 
-    /// Residual format-only widget for datetime columns — owns
-    /// `date_format` only. Pair with primitive `Enum` and `Color` fields
-    /// for `datetime_color_mode` + `color` to fully decompose datetime
-    /// styling.
-    DatetimeFormat,
-    /// Residual format-only widget for string columns — owns `format`
-    /// only. Pair with primitive `Enum` and `Color` fields for
-    /// `string_color_mode` + `color` to fully decompose string styling.
+        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+        discrete: bool,
+    },
+    DatetimeFormat {
+        /// Plugin-declared default `date_format`, shown by the editor in
+        /// unedited fields and elided from serialized configs.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        default: Option<DatetimeFormatType>,
+    },
     StringFormat,
     NumberSeriesStyle {
         default: NumberSeriesStyleDefaultConfig,
@@ -127,8 +132,19 @@ pub enum ControlSpec {
     Symbols {
         default: KeyValueOpts,
     },
-    NumberFormat,
+    NumberFormat {
+        /// Plugin-declared default format, keyed like `number_format`
+        /// itself.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        default: Option<CustomNumberFormatConfig>,
+    },
     AggregateDepth,
+
+    Group {
+        key: String,
+        #[serde(default)]
+        fields: Vec<ControlSpec>,
+    },
 }
 
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
@@ -138,6 +154,143 @@ pub struct EnumVariant {
     pub label: Option<String>,
 }
 
+/// One stop of a [`ControlSpec::GradientStops`] value in its in-memory
+/// form: a `#rrggbb` color at `offset` ∈ `[0, 1]`.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+pub struct GradientStopSpec {
+    pub color: String,
+    pub offset: f64,
+}
+
+/// The [`ControlSpec::GradientStops`] canonical stop order: offsets
+/// clamped to `[0, 1]` and rounded to 3 decimals, stops sorted stably
+/// by offset.
+pub fn canonicalize_gradient_stops(mut stops: Vec<GradientStopSpec>) -> Vec<GradientStopSpec> {
+    for stop in &mut stops {
+        stop.offset = (stop.offset.clamp(0.0, 1.0) * 1000.0).round() / 1000.0;
+    }
+
+    stops.sort_by(|a, b| {
+        a.offset
+            .partial_cmp(&b.offset)
+            .unwrap_or(std::cmp::Ordering::Equal)
+    });
+
+    stops
+}
+
+/// Fit `stops` to a `discrete` field's fixed pair: an over-length value
+/// keeps only its two end colors, pinned to `0`/`1`.
+pub fn discrete_pair(stops: Vec<GradientStopSpec>) -> Vec<GradientStopSpec> {
+    let stops = canonicalize_gradient_stops(stops);
+    match (stops.first(), stops.last()) {
+        (Some(first), Some(last)) if stops.len() > 2 => vec![
+            GradientStopSpec {
+                color: first.color.clone(),
+                offset: 0.0,
+            },
+            GradientStopSpec {
+                color: last.color.clone(),
+                offset: 1.0,
+            },
+        ],
+        _ => stops,
+    }
+}
+
+impl ColumnConfigSchema {
+    pub fn canonicalize(self) -> Self {
+        self.canonicalize_defaults().group_format_controls()
+    }
+
+    pub fn group_format_controls(mut self) -> Self {
+        fn is_format(spec: &ControlSpec) -> bool {
+            matches!(
+                spec,
+                ControlSpec::NumberFormat { .. }
+                    | ControlSpec::DatetimeFormat { .. }
+                    | ControlSpec::StringFormat
+            )
+        }
+
+        fn walk(fields: &mut Vec<ControlSpec>) {
+            for spec in fields.iter_mut() {
+                if let ControlSpec::Group { key, fields } = spec
+                    && key != "format"
+                {
+                    walk(fields);
+                }
+            }
+
+            let first = fields.iter().position(is_format);
+            if let Some(first) = first {
+                let mut formats = vec![];
+                let mut i = first;
+                while i < fields.len() {
+                    if is_format(&fields[i]) {
+                        formats.push(fields.remove(i));
+                    } else {
+                        i += 1;
+                    }
+                }
+
+                fields.insert(first, ControlSpec::Group {
+                    key: "format".to_owned(),
+                    fields: formats,
+                });
+            }
+        }
+
+        walk(&mut self.fields);
+        self
+    }
+
+    /// Canonicalize every CSS-valued default at schema ingest, dropping
+    /// (and logging) fields whose default fails its kind's reader.
+    pub fn canonicalize_defaults(mut self) -> Self {
+        fn canonicalize_specs(fields: &mut Vec<ControlSpec>) {
+            fields.retain_mut(|spec| {
+                let (kind, key, default) = match spec {
+                    ControlSpec::Group { fields, .. } => {
+                        canonicalize_specs(fields);
+                        return !fields.is_empty();
+                    },
+                    ControlSpec::Color { key, default } => (CssKind::Color, key, default),
+                    ControlSpec::Palette { key, default, .. } => (CssKind::Palette, key, default),
+                    ControlSpec::GradientStops { key, default, .. } => {
+                        (CssKind::Gradient, key, default)
+                    },
+                    _ => return true,
+                };
+
+                match kind.canonicalize(default) {
+                    Ok(canonical) => {
+                        *default = canonical;
+                        true
+                    },
+                    Err(error) => {
+                        tracing::error!("Dropping `{key}` — invalid schema default: {error}");
+                        false
+                    },
+                }
+            });
+        }
+
+        canonicalize_specs(&mut self.fields);
+        self
+    }
+
+    /// The CSS kind of the control owning `key`, if it is CSS-valued.
+    pub fn css_kind_of(&self, key: &str) -> Option<CssKind> {
+        self.leaf_fields().into_iter().find_map(|spec| match spec {
+            ControlSpec::Color { key: k, .. } if k == key => Some(CssKind::Color),
+            ControlSpec::Palette { key: k, .. } if k == key => Some(CssKind::Palette),
+            ControlSpec::GradientStops { key: k, .. } if k == key => Some(CssKind::Gradient),
+            _ => None,
+        })
+    }
+}
+
 impl ControlSpec {
     /// Top-level JSON keys this control owns when its value is serialized
     /// into a column's config map. For primitives this is just `[key]`;
@@ -146,20 +299,22 @@ impl ControlSpec {
     /// `columns_config` blob passed to `plugin.restore()`.
     pub fn serialized_keys(&self) -> Vec<&str> {
         match self {
-            ControlSpec::DatetimeFormat => vec!["date_format"],
+            ControlSpec::DatetimeFormat { .. } => vec!["date_format"],
             ControlSpec::StringFormat => vec!["format"],
             ControlSpec::NumberSeriesStyle { .. } => vec!["chart_type", "stack"],
             ControlSpec::Symbols { .. } => vec!["symbols"],
-            ControlSpec::NumberFormat => vec!["number_format"],
+            ControlSpec::NumberFormat { .. } => vec!["number_format"],
             ControlSpec::AggregateDepth => vec!["aggregate_depth"],
-            ControlSpec::ColorRange {
-                key_pos, key_neg, ..
-            } => vec![key_pos.as_str(), key_neg.as_str()],
             ControlSpec::Enum { key, .. }
             | ControlSpec::Bool { key, .. }
             | ControlSpec::Number { key, .. }
             | ControlSpec::String { key, .. }
-            | ControlSpec::Color { key, .. } => vec![key.as_str()],
+            | ControlSpec::Color { key, .. }
+            | ControlSpec::Palette { key, .. }
+            | ControlSpec::GradientStops { key, .. } => vec![key.as_str()],
+            ControlSpec::Group { fields, .. } => {
+                fields.iter().flat_map(|f| f.serialized_keys()).collect()
+            },
         }
     }
 }
@@ -168,12 +323,6 @@ impl ControlSpec {
 /// declares which top-level keys the update is allowed to write
 /// (`keys` — equivalent to the field's [`ControlSpec::serialized_keys`])
 /// and a partial new sub-state (`value`).
-///
-/// Apply semantics: keys in `keys` are *cleared* from the column's config
-/// map, then keys present in `value` are *inserted*. Defaults are
-/// pre-stripped by the caller (typically via `skip_serializing_if`), so
-/// "no value set for key K" means the schema default applies and K is
-/// not serialized.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct ColumnConfigFieldUpdate {
     pub keys: Vec<String>,
@@ -193,3 +342,244 @@ pub fn filter_to_schema(
         .map(|(k, v)| (k.clone(), v.clone()))
         .collect()
 }
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    fn color(key: &str, default: &str) -> ControlSpec {
+        ControlSpec::Color {
+            key: key.to_owned(),
+            default: default.to_owned(),
+        }
+    }
+
+    fn flag(key: &str) -> ControlSpec {
+        ControlSpec::Bool {
+            key: key.to_owned(),
+            default: false,
+        }
+    }
+
+    fn group(key: &str, fields: Vec<ControlSpec>) -> ControlSpec {
+        ControlSpec::Group {
+            key: key.to_owned(),
+            fields,
+        }
+    }
+
+    #[test]
+    fn group_deserializes_recursively() {
+        let schema: ColumnConfigSchema = serde_json::from_value(json!({
+            "fields": [{
+                "kind": "Group",
+                "key": "legend",
+                "fields": [
+                    { "kind": "Bool", "key": "legend_on", "default": false },
+                    {
+                        "kind": "Group",
+                        "key": "inner",
+                        "fields": [{ "kind": "Color", "key": "color", "default": "#ff0000" }]
+                    }
+                ]
+            }]
+        }))
+        .unwrap();
+
+        let keys = schema.active_keys();
+        assert_eq!(
+            keys,
+            HashSet::from(["legend_on".to_owned(), "color".to_owned()])
+        );
+
+        let leaves = schema.leaf_fields();
+        assert_eq!(leaves.len(), 2);
+        assert!(
+            leaves
+                .iter()
+                .all(|s| !matches!(s, ControlSpec::Group { .. }))
+        );
+    }
+
+    #[test]
+    fn grouped_schema_is_equivalent_to_flat() {
+        let flat = ColumnConfigSchema {
+            fields: vec![flag("stack"), color("color", "#0366d6")],
+        };
+
+        let grouped = ColumnConfigSchema {
+            fields: vec![group("series", vec![
+                flag("stack"),
+                color("color", "#0366d6"),
+            ])],
+        };
+
+        assert_eq!(flat.active_keys(), grouped.active_keys());
+        assert_eq!(flat.css_kind_of("color"), grouped.css_kind_of("color"));
+        assert_eq!(flat.css_kind_of("stack"), grouped.css_kind_of("stack"));
+    }
+
+    #[test]
+    fn format_controls_group_and_merge() {
+        let schema = ColumnConfigSchema {
+            fields: vec![
+                ControlSpec::NumberFormat { default: None },
+                flag("flag"),
+                ControlSpec::StringFormat,
+            ],
+        }
+        .group_format_controls();
+
+        assert_eq!(schema.fields.len(), 2);
+        let ControlSpec::Group { key, fields } = &schema.fields[0] else {
+            panic!("expected format group first");
+        };
+
+        assert_eq!(key, "format");
+        assert!(matches!(fields[0], ControlSpec::NumberFormat { .. }));
+        assert!(matches!(fields[1], ControlSpec::StringFormat));
+        assert!(matches!(&schema.fields[1], ControlSpec::Bool { .. }));
+
+        assert_eq!(
+            schema.active_keys(),
+            HashSet::from([
+                "number_format".to_owned(),
+                "format".to_owned(),
+                "flag".to_owned()
+            ])
+        );
+    }
+
+    #[test]
+    fn format_grouping_recurses_but_never_double_wraps() {
+        let schema = ColumnConfigSchema {
+            fields: vec![
+                group("format", vec![ControlSpec::NumberFormat { default: None }]),
+                group("styling", vec![flag("x"), ControlSpec::DatetimeFormat {
+                    default: None,
+                }]),
+            ],
+        }
+        .group_format_controls();
+
+        let ControlSpec::Group { key, fields } = &schema.fields[0] else {
+            panic!("expected group");
+        };
+
+        assert_eq!(key, "format");
+        assert!(matches!(fields[0], ControlSpec::NumberFormat { .. }));
+
+        let ControlSpec::Group { fields, .. } = &schema.fields[1] else {
+            panic!("expected group");
+        };
+
+        assert!(matches!(
+            &fields[1],
+            ControlSpec::Group { key, fields }
+                if key == "format" && matches!(fields[0], ControlSpec::DatetimeFormat { .. })
+        ));
+    }
+
+    #[test]
+    fn format_controls_deserialize_without_default_payload() {
+        let schema: ColumnConfigSchema = serde_json::from_value(json!({
+            "fields": [{ "kind": "NumberFormat" }, { "kind": "DatetimeFormat" }]
+        }))
+        .unwrap();
+
+        assert!(matches!(&schema.fields[0], ControlSpec::NumberFormat {
+            default: None
+        }));
+        assert!(matches!(&schema.fields[1], ControlSpec::DatetimeFormat {
+            default: None
+        }));
+    }
+
+    #[test]
+    fn number_format_default_payload_deserializes_flattened_families() {
+        let schema: ColumnConfigSchema = serde_json::from_value(json!({
+            "fields": [{
+                "kind": "NumberFormat",
+                "default": {
+                    "notation": "compact",
+                    "compactDisplay": "short",
+                    "minimumFractionDigits": 0,
+                    "maximumFractionDigits": 1
+                }
+            }]
+        }))
+        .unwrap();
+
+        let ControlSpec::NumberFormat {
+            default: Some(default),
+        } = &schema.fields[0]
+        else {
+            panic!("expected NumberFormat with default");
+        };
+
+        assert_eq!(
+            default._notation,
+            Some(crate::config::Notation::Compact(
+                crate::config::CompactDisplay::Short
+            ))
+        );
+        assert_eq!(default._style, None);
+        assert_eq!(default.minimum_fraction_digits, Some(0.));
+        assert_eq!(default.maximum_fraction_digits, Some(1.));
+        assert_eq!(
+            schema.active_keys(),
+            HashSet::from(["number_format".to_owned()])
+        );
+    }
+
+    #[test]
+    fn datetime_format_default_payload_deserializes_simple_arm() {
+        let schema: ColumnConfigSchema = serde_json::from_value(json!({
+            "fields": [{
+                "kind": "DatetimeFormat",
+                "default": { "dateStyle": "medium", "timeStyle": "disabled" }
+            }]
+        }))
+        .unwrap();
+
+        let ControlSpec::DatetimeFormat {
+            default: Some(DatetimeFormatType::Simple(simple)),
+        } = &schema.fields[0]
+        else {
+            panic!("expected DatetimeFormat with Simple default");
+        };
+
+        assert_eq!(
+            simple.date_style,
+            crate::config::SimpleDatetimeFormat::Medium
+        );
+        assert_eq!(
+            simple.time_style,
+            crate::config::SimpleDatetimeFormat::Disabled
+        );
+    }
+
+    #[test]
+    fn canonicalize_defaults_recurses_and_drops_empty_groups() {
+        let schema = ColumnConfigSchema {
+            fields: vec![
+                group("ok", vec![color("good", "RGB(255,0,0)"), flag("flag")]),
+                group("doomed", vec![color("bad", "not-a-color")]),
+            ],
+        }
+        .canonicalize_defaults();
+
+        assert_eq!(schema.fields.len(), 1);
+        let ControlSpec::Group { key, fields } = &schema.fields[0] else {
+            panic!("expected group");
+        };
+
+        assert_eq!(key, "ok");
+        assert!(matches!(
+            &fields[0],
+            ControlSpec::Color { default, .. } if default == "#ff0000"
+        ));
+    }
+}