@perspective-dev/viewer 5.4.0 → 5.5.1

package/src/rust/config/column_config_schema.rs

@@ -74,6 +74,38 @@ pub enum ControlSpec {
         variants: Vec<EnumVariant>,
         default: String,
     },
+
+    /// A CSS `font-family` picked from the generic keywords plus the families
+    /// the host can enumerate, with optional size, bold and italic inputs
+    /// each bound to its own key.
+    Font {
+        key: String,
+        default: String,
+
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        size: Option<FontSize>,
+
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        bold: Option<FontToggle>,
+
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        italic: Option<FontToggle>,
+    },
+    /// A 3×3 anchor picker whose value is one of the nine [`Alignment`]
+    /// tokens.
+    Alignment {
+        key: String,
+
+        /// The cell shown as the unmodified value and elided from serialized
+        /// configs, or `None` when an unset key stands for something no cell
+        /// can show.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        default: Option<Alignment>,
+
+        /// Only the four corner cells are selectable.
+        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+        corners: bool,
+    },
     Bool {
         key: String,
         default: bool,
@@ -125,7 +157,6 @@ pub enum ControlSpec {
         #[serde(default, skip_serializing_if = "Option::is_none")]
         default: Option<DatetimeFormatType>,
     },
-    StringFormat,
     NumberSeriesStyle {
         default: NumberSeriesStyleDefaultConfig,
     },
@@ -147,6 +178,108 @@ pub enum ControlSpec {
     },
 }
 
+/// One cell of a 3×3 anchor grid: a corner `top-left`/`top-right`/
+/// `bottom-left`/`bottom-right`, an edge `top`/`left`/`right`/`bottom`, or
+/// `center`.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Alignment {
+    TopLeft,
+    Top,
+    TopRight,
+    Left,
+    Center,
+    Right,
+    BottomLeft,
+    Bottom,
+    BottomRight,
+}
+
+impl Alignment {
+    /// Every cell in row-major order.
+    pub const ALL: [Alignment; 9] = [
+        Alignment::TopLeft,
+        Alignment::Top,
+        Alignment::TopRight,
+        Alignment::Left,
+        Alignment::Center,
+        Alignment::Right,
+        Alignment::BottomLeft,
+        Alignment::Bottom,
+        Alignment::BottomRight,
+    ];
+    pub const CORNERS: [Alignment; 4] = [
+        Alignment::TopLeft,
+        Alignment::TopRight,
+        Alignment::BottomLeft,
+        Alignment::BottomRight,
+    ];
+
+    pub fn is_corner(self) -> bool {
+        Self::CORNERS.contains(&self)
+    }
+
+    /// The serialized token.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Alignment::TopLeft => "top-left",
+            Alignment::Top => "top",
+            Alignment::TopRight => "top-right",
+            Alignment::Left => "left",
+            Alignment::Center => "center",
+            Alignment::Right => "right",
+            Alignment::BottomLeft => "bottom-left",
+            Alignment::Bottom => "bottom",
+            Alignment::BottomRight => "bottom-right",
+        }
+    }
+
+    pub fn parse(src: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|x| x.as_str() == src)
+    }
+
+    /// `Top Left`-style text for accessible names.
+    pub fn humanized(self) -> String {
+        self.as_str()
+            .split('-')
+            .map(|word| {
+                let mut chars = word.chars();
+                match chars.next() {
+                    Some(first) => first.to_uppercase().chain(chars).collect::<String>(),
+                    None => String::new(),
+                }
+            })
+            .collect::<Vec<_>>()
+            .join(" ")
+    }
+}
+
+/// One boolean style toggle of a [`ControlSpec::Font`] control: the
+/// config key it writes and the value that counts as "not set".
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+pub struct FontToggle {
+    pub key: String,
+    #[serde(default)]
+    pub default: bool,
+}
+
+/// The size input of a [`ControlSpec::Font`] control: a number (CSS px)
+/// under its own key, elided from serialized configs at `default`.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+pub struct FontSize {
+    pub key: String,
+    pub default: f64,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub min: Option<f64>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max: Option<f64>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub step: Option<f64>,
+}
+
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub struct EnumVariant {
     pub value: String,
@@ -182,9 +315,7 @@ impl ColumnConfigSchema {
         fn is_format(spec: &ControlSpec) -> bool {
             matches!(
                 spec,
-                ControlSpec::NumberFormat { .. }
-                    | ControlSpec::DatetimeFormat { .. }
-                    | ControlSpec::StringFormat
+                ControlSpec::NumberFormat { .. } | ControlSpec::DatetimeFormat { .. }
             )
         }
 
@@ -230,6 +361,18 @@ impl ColumnConfigSchema {
                         canonicalize_specs(fields);
                         return !fields.is_empty();
                     },
+                    ControlSpec::Alignment {
+                        key,
+                        default: Some(default),
+                        corners: true,
+                    } if !default.is_corner() => {
+                        tracing::error!(
+                            "Dropping `{key}` — default `{}` is not a corner",
+                            default.as_str()
+                        );
+
+                        return false;
+                    },
                     ControlSpec::Color { key, default } => (CssKind::Color, key, default),
                     ControlSpec::Palette { key, default, .. } => (CssKind::Palette, key, default),
                     ControlSpec::GradientStops { key, default, .. } => {
@@ -255,6 +398,16 @@ impl ColumnConfigSchema {
         self
     }
 
+    /// The variants of the [`ControlSpec::Enum`] owning `key`, if any.
+    pub fn enum_variants_of(&self, key: &str) -> Option<&[EnumVariant]> {
+        self.leaf_fields().into_iter().find_map(|spec| match spec {
+            ControlSpec::Enum {
+                key: k, variants, ..
+            } if k == key => Some(variants.as_slice()),
+            _ => None,
+        })
+    }
+
     /// 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 {
@@ -275,12 +428,27 @@ impl ControlSpec {
     pub fn serialized_keys(&self) -> Vec<&str> {
         match self {
             ControlSpec::DatetimeFormat { .. } => vec!["date_format"],
-            ControlSpec::StringFormat => vec!["format"],
+            ControlSpec::Font {
+                key,
+                size,
+                bold,
+                italic,
+                ..
+            } => [
+                Some(key.as_str()),
+                size.as_ref().map(|s| s.key.as_str()),
+                bold.as_ref().map(|t| t.key.as_str()),
+                italic.as_ref().map(|t| t.key.as_str()),
+            ]
+            .into_iter()
+            .flatten()
+            .collect(),
             ControlSpec::NumberSeriesStyle { .. } => vec!["chart_type", "stack"],
             ControlSpec::Symbols { .. } => vec!["symbols"],
             ControlSpec::NumberFormat { .. } => vec!["number_format"],
             ControlSpec::AggregateDepth => vec!["aggregate_depth"],
             ControlSpec::Enum { key, .. }
+            | ControlSpec::Alignment { key, .. }
             | ControlSpec::Bool { key, .. }
             | ControlSpec::Number { key, .. }
             | ControlSpec::String { key, .. }
@@ -396,13 +564,46 @@ mod tests {
         assert_eq!(flat.css_kind_of("stack"), grouped.css_kind_of("stack"));
     }
 
+    #[test]
+    fn enum_variants_see_through_groups() {
+        let mode = ControlSpec::Enum {
+            key: "fg_mode".to_owned(),
+            default: "color".to_owned(),
+            variants: vec![
+                EnumVariant {
+                    value: "disabled".to_owned(),
+                    label: None,
+                },
+                EnumVariant {
+                    value: "color".to_owned(),
+                    label: None,
+                },
+            ],
+        };
+
+        let grouped = ColumnConfigSchema {
+            fields: vec![group("color", vec![mode, flag("flag")])],
+        };
+
+        let values: Vec<&str> = grouped
+            .enum_variants_of("fg_mode")
+            .unwrap()
+            .iter()
+            .map(|v| v.value.as_str())
+            .collect();
+
+        assert_eq!(values, vec!["disabled", "color"]);
+        assert!(grouped.enum_variants_of("flag").is_none());
+        assert!(grouped.enum_variants_of("missing").is_none());
+    }
+
     #[test]
     fn format_controls_group_and_merge() {
         let schema = ColumnConfigSchema {
             fields: vec![
                 ControlSpec::NumberFormat { default: None },
                 flag("flag"),
-                ControlSpec::StringFormat,
+                ControlSpec::DatetimeFormat { default: None },
             ],
         }
         .group_format_controls();
@@ -414,19 +615,45 @@ mod tests {
 
         assert_eq!(key, "format");
         assert!(matches!(fields[0], ControlSpec::NumberFormat { .. }));
-        assert!(matches!(fields[1], ControlSpec::StringFormat));
+        assert!(matches!(fields[1], ControlSpec::DatetimeFormat { .. }));
         assert!(matches!(&schema.fields[1], ControlSpec::Bool { .. }));
 
         assert_eq!(
             schema.active_keys(),
             HashSet::from([
                 "number_format".to_owned(),
-                "format".to_owned(),
+                "date_format".to_owned(),
                 "flag".to_owned()
             ])
         );
     }
 
+    #[test]
+    fn font_owns_its_size_and_toggle_keys() {
+        let spec = ControlSpec::Font {
+            key: "font_family".to_owned(),
+            default: "inherit".to_owned(),
+            size: Some(FontSize {
+                key: "font_size".to_owned(),
+                default: 12.0,
+                min: None,
+                max: None,
+                step: None,
+            }),
+            bold: Some(FontToggle {
+                key: "bold".to_owned(),
+                default: false,
+            }),
+            italic: None,
+        };
+
+        assert_eq!(spec.serialized_keys(), vec![
+            "font_family",
+            "font_size",
+            "bold"
+        ]);
+    }
+
     #[test]
     fn format_grouping_recurses_but_never_double_wraps() {
         let schema = ColumnConfigSchema {
@@ -536,6 +763,83 @@ mod tests {
         );
     }
 
+    #[test]
+    fn alignment_tokens_round_trip() {
+        for align in Alignment::ALL {
+            assert_eq!(Alignment::parse(align.as_str()), Some(align));
+            assert_eq!(serde_json::to_value(align).unwrap(), json!(align.as_str()));
+        }
+
+        for bad in ["middle", "left-top", "top-center", "middle-left", ""] {
+            assert_eq!(Alignment::parse(bad), None, "{bad}");
+        }
+
+        assert_eq!(Alignment::ALL.iter().filter(|x| x.is_corner()).count(), 4);
+        assert_eq!(Alignment::TopLeft.humanized(), "Top Left");
+        assert_eq!(Alignment::Center.humanized(), "Center");
+    }
+
+    #[test]
+    fn alignment_deserializes_with_optional_default_and_corners() {
+        let schema: ColumnConfigSchema = serde_json::from_value(json!({
+            "fields": [
+                { "kind": "Alignment", "key": "align" },
+                { "kind": "Alignment", "key": "legend_anchor", "default": "top-right", "corners": true }
+            ]
+        }))
+        .unwrap();
+
+        assert!(matches!(&schema.fields[0], ControlSpec::Alignment {
+            default: None,
+            corners: false,
+            ..
+        }));
+        assert!(matches!(&schema.fields[1], ControlSpec::Alignment {
+            default: Some(Alignment::TopRight),
+            corners: true,
+            ..
+        }));
+        assert_eq!(
+            schema.active_keys(),
+            HashSet::from(["align".to_owned(), "legend_anchor".to_owned()])
+        );
+        assert!(
+            serde_json::from_value::<ColumnConfigSchema>(json!({
+                "fields": [{ "kind": "Alignment", "key": "x", "default": "middle" }]
+            }))
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn canonicalize_defaults_drops_non_corner_default_of_corners_field() {
+        let schema = ColumnConfigSchema {
+            fields: vec![
+                ControlSpec::Alignment {
+                    key: "bad".to_owned(),
+                    default: Some(Alignment::Top),
+                    corners: true,
+                },
+                ControlSpec::Alignment {
+                    key: "ok".to_owned(),
+                    default: Some(Alignment::Top),
+                    corners: false,
+                },
+                ControlSpec::Alignment {
+                    key: "unset".to_owned(),
+                    default: None,
+                    corners: true,
+                },
+            ],
+        }
+        .canonicalize_defaults();
+
+        assert_eq!(
+            schema.active_keys(),
+            HashSet::from(["ok".to_owned(), "unset".to_owned()])
+        );
+    }
+
     #[test]
     fn canonicalize_defaults_recurses_and_drops_empty_groups() {
         let schema = ColumnConfigSchema {

package/src/rust/config/datetime_column_style.rs

@@ -10,13 +10,11 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-mod color_mode;
 mod custom;
 mod custom_format;
 mod simple;
 mod simple_format;
 
-pub use color_mode::*;
 pub use custom::*;
 pub use custom_format::*;
 use serde::{Deserialize, Serialize};
@@ -65,13 +63,4 @@ pub struct DatetimeColumnStyleConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     #[ts(optional, as = "Option<_>")]
     pub date_format: Option<DatetimeFormatType>,
-
-    #[serde(default)]
-    #[serde(skip_serializing_if = "DatetimeColorMode::is_none")]
-    pub datetime_color_mode: DatetimeColorMode,
-
-    #[serde(default)]
-    #[serde(skip_serializing_if = "Option::is_none")]
-    #[ts(skip)]
-    pub color: Option<String>,
 }

package/src/rust/config/export_method.rs

@@ -69,6 +69,24 @@ pub enum ExportMethod {
     #[serde(rename = "arrow-all")]
     ArrowAll,
 
+    #[serde(rename = "arrow-lz4")]
+    ArrowLz4,
+
+    #[serde(rename = "arrow-lz4-selected")]
+    ArrowLz4Selected,
+
+    #[serde(rename = "arrow-lz4-all")]
+    ArrowLz4All,
+
+    #[serde(rename = "arrow-zstd")]
+    ArrowZstd,
+
+    #[serde(rename = "arrow-zstd-selected")]
+    ArrowZstdSelected,
+
+    #[serde(rename = "arrow-zstd-all")]
+    ArrowZstdAll,
+
     #[serde(rename = "json-config")]
     JsonConfig,
 }
@@ -94,6 +112,12 @@ impl ExportMethod {
             Self::CsvSelected => ".selected.csv",
             Self::JsonSelected => ".selected.json",
             Self::ArrowSelected => ".selected.arrow",
+            Self::ArrowLz4 => ".lz4.arrow",
+            Self::ArrowLz4Selected => ".selected.lz4.arrow",
+            Self::ArrowLz4All => ".all.lz4.arrow",
+            Self::ArrowZstd => ".zstd.arrow",
+            Self::ArrowZstdSelected => ".selected.zstd.arrow",
+            Self::ArrowZstdAll => ".all.zstd.arrow",
             Self::Ndjson => ".ndjson",
             Self::NdjsonAll => ".all.ndjson",
             Self::NdjsonSelected => ".selected.ndjson",

package/src/rust/config/mod.rs

@@ -22,7 +22,6 @@ mod number_series_style;
 mod number_string_format;
 mod options;
 mod plugin_static_config;
-mod string_column_style;
 pub mod view_config;
 mod viewer_config;
 mod workspace_config;
@@ -35,7 +34,6 @@ pub use number_series_style::*;
 pub use number_string_format::*;
 pub use options::*;
 pub use plugin_static_config::*;
-pub use string_column_style::*;
 pub use view_config::*;
 pub use viewer_config::*;
 pub use workspace_config::*;

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)]