@perspective-dev/viewer 5.1.0 → 5.3.0

package/src/rust/config/datetime_column_style/custom.rs

@@ -62,14 +62,22 @@ const fn numeric_default() -> u32 {
     0
 }
 
+/// A datetime column's `date_format` in its `Custom` form: per-part
+/// `Intl.DateTimeFormatOptions` overrides, discriminated from the `Simple`
+/// preset form by the required `format: "custom"` key. Each part is a
+/// [`CustomDatetimeFormat`] variant valid for that `Intl` option;
+/// `"disabled"` omits the part from the formatted output entirely.
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize, TS)]
 pub struct CustomDatetimeStyleConfig {
     format: FormatUnit,
 
+    /// An IANA time zone name (e.g. `"America/New_York"`); defaults to the
+    /// browser's local time zone.
     #[serde(default)]
     #[serde(rename = "timeZone", skip_serializing_if = "Option::is_none")]
     pub time_zone: Option<String>,
 
+    /// Sub-second digits to display, 0-3 (0 = none).
     #[serde(
         skip_serializing_if = "is_zero",
         rename = "fractionalSecondDigits",
@@ -77,27 +85,36 @@ pub struct CustomDatetimeStyleConfig {
     )]
     pub fractional_seconds: u32,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub second: CustomDatetimeFormat,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub minute: CustomDatetimeFormat,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub hour: CustomDatetimeFormat,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub day: CustomDatetimeFormat,
 
+    /// A name form (`"long"`/`"short"`/`"narrow"`); defaults to
+    /// `"disabled"` (weekday not shown).
     #[serde(skip_serializing_if = "is_disabled", default = "weekday_default")]
     pub weekday: CustomDatetimeFormat,
 
+    /// Numeric or name form; defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub month: CustomDatetimeFormat,
 
+    /// Defaults to `"2-digit"`.
     #[serde(skip_serializing_if = "is_two_digit", default = "year_default")]
     pub year: CustomDatetimeFormat,
 
+    /// 12-hour clock; defaults to `true`.
     #[serde(skip_serializing_if = "is_true", default = "hour12_default")]
     pub hour12: bool,
 }

package/src/rust/config/datetime_column_style/simple.rs

@@ -23,12 +23,20 @@ const fn time_style_default() -> SimpleDatetimeFormat {
     SimpleDatetimeFormat::Medium
 }
 
+/// A datetime column's `date_format` in its `Simple` preset form:
+/// `Intl.DateTimeFormatOptions`' `dateStyle`/`timeStyle` presets. This is
+/// the default form (no `format` key); setting `format: "custom"` selects
+/// the per-part `CustomDatetimeStyleConfig` instead.
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize, TS)]
 pub struct SimpleDatetimeStyleConfig {
+    /// An IANA time zone name (e.g. `"America/New_York"`); defaults to the
+    /// browser's local time zone.
     #[serde(default)]
     #[serde(rename = "timeZone", skip_serializing_if = "Option::is_none")]
     pub time_zone: Option<String>,
 
+    /// Date preset breadth, or `"disabled"` to omit the date entirely;
+    /// defaults to `"short"`.
     #[serde(
         default = "date_style_default",
         rename = "dateStyle",
@@ -36,6 +44,8 @@ pub struct SimpleDatetimeStyleConfig {
     )]
     pub date_style: SimpleDatetimeFormat,
 
+    /// Time preset breadth, or `"disabled"` to omit the time entirely;
+    /// defaults to `"medium"`.
     #[serde(
         default = "time_style_default",
         rename = "timeStyle",

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/number_string_format.rs

@@ -16,6 +16,11 @@ use serde::{Deserialize, Serialize};
 use strum::{Display, EnumIter};
 use ts_rs::TS;
 
+/// The `style` family of a numeric column's `number_format` — serialized
+/// FLATTENED into [`CustomNumberFormatConfig`]'s object, discriminated by
+/// the `style` key (`"decimal"` default, `"currency"` + `currency`/
+/// `currencyDisplay`/`currencySign`, `"percent"`, `"unit"` + `unit`/
+/// `unitDisplay`), mirroring `Intl.NumberFormat` options.
 #[derive(Serialize, Deserialize, Default, Debug, PartialEq, Clone, TS)]
 #[serde(rename_all = "camelCase", tag = "style")]
 pub enum NumberFormatStyle {
@@ -127,6 +132,11 @@ pub enum TrailingZeroDisplay {
     StripIfInteger,
 }
 
+/// The `notation` family of a numeric column's `number_format` —
+/// serialized FLATTENED into [`CustomNumberFormatConfig`]'s object,
+/// discriminated by the `notation` key (`"standard"` default,
+/// `"scientific"`, `"engineering"`, `"compact"` + `compactDisplay`),
+/// mirroring `Intl.NumberFormat` options.
 #[derive(Serialize, Deserialize, Default, Debug, PartialEq, Clone, TS)]
 #[serde(rename_all = "camelCase", tag = "notation")]
 pub enum Notation {
@@ -169,6 +179,14 @@ pub enum SignDisplay {
     Never,
 }
 
+/// A numeric column's `number_format` (`columns_config` value) —
+/// `Intl.NumberFormat`-shaped options, written by the Style tab's number
+/// format editor and read by `createNumberFormatter`. The `style` and
+/// `notation` families ([`NumberFormatStyle`] / [`Notation`]) are serde-
+/// FLATTENED into this object but `#[ts(skip)]`'d (ts-rs cannot flatten
+/// `Option<enum>`) — the package's `NumberFormatConfig` re-composes the
+/// full wire type as `CustomNumberFormatConfig & Partial<NumberFormatStyle>
+/// & Partial<Notation>` (see `column-format.ts`).
 #[derive(Serialize, Deserialize, Debug, Default, PartialEq, Clone, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct CustomNumberFormatConfig {
@@ -181,33 +199,42 @@ pub struct CustomNumberFormatConfig {
     // these min/max props can all be specified but it results in possible conflicts
     // may consider making them distinct options
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub minimum_integer_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub minimum_fraction_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub maximum_fraction_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub minimum_significant_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub maximum_significant_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub rounding_priority: Option<RoundingPriority>,
 
     // specific values https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingincrement
     // Only available with automatic rounding priority
     // Cannot be mixed with sigfig rounding. (Does this mean max/min sigfig must be unset?)
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub rounding_increment: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub rounding_mode: Option<RoundingMode>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub trailing_zero_display: Option<TrailingZeroDisplay>,
 
     #[serde(flatten)]
@@ -215,10 +242,16 @@ pub struct CustomNumberFormatConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub _notation: Option<Notation>,
 
+    /// NOTE (audit 2026-08-05): serialized values are the STRINGS
+    /// `"always"`/`"auto"`/`"min2"` or the untagged BOOLEAN `false` —
+    /// the former hand-written TS `useGrouping?: boolean` was wrong for
+    /// the string cases.
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub use_grouping: Option<UseGrouping>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub sign_display: Option<SignDisplay>,
 }
 

package/src/rust/config/options.rs

@@ -28,6 +28,24 @@ pub struct PanelOptions {
     pub panel: Option<String>,
 }
 
+/// Options for the `restore()` method.
+#[derive(Deserialize, Default, TS)]
+pub struct RestoreOptions {
+    /// The target panel; the active panel when omitted.
+    #[ts(optional)]
+    pub panel: Option<String>,
+
+    /// When `true`, a failed restore only REJECTS the returned `Promise` —
+    /// the error is not committed to the viewer's visible error state, and
+    /// the session remains usable for subsequent calls. For programmatic
+    /// callers (e.g. the LLM agent's `set_view_config` tool) for whom a
+    /// failed config patch is feedback rather than a user-facing fault.
+    /// The config may be partially applied on failure; restore a
+    /// known-good config to recover exactly.
+    #[ts(optional)]
+    pub suppress_errors: Option<bool>,
+}
+
 /// The `eject` argument: the loaded client to remove by name; the active
 /// panel's client when omitted.
 #[derive(Deserialize, Default, TS)]
@@ -69,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/plugin_static_config.rs

@@ -10,7 +10,7 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-use perspective_client::config::GroupRollupMode;
+use perspective_client::config::{GroupRollupMode, SplitRollupMode};
 use serde::Deserialize;
 use ts_rs::TS;
 
@@ -103,6 +103,13 @@ pub struct PluginStaticConfig {
     #[ts(optional)]
     pub group_rollup_modes: Option<Vec<GroupRollupMode>>,
 
+    /// Split-rollup modes the plugin accepts, in preference order.
+    /// The first entry that matches a feature flag becomes the default.
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub split_rollup_modes: Option<Vec<SplitRollupMode>>,
+
     /// Plugin load priority. Higher numbers win; ties resolve in
     /// registration order. The highest-priority plugin is loaded by
     /// default unless `restore({ plugin })` overrides it.
@@ -120,15 +127,70 @@ pub struct PluginStaticConfig {
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub can_render_column_styles: bool,
+
+    /// What `group_by` MEANS visually for this plugin, e.g. `"X Axis"`
+    /// for the Y-series charts or `"Hierarchy"` for treemap/sunburst.
+    /// `None` where the field has no visual role of its own and is a
+    /// plain aggregation key (the X/Y charts, whose axes both come from
+    /// `columns`).
+    ///
+    /// This is the `group_by` counterpart of [`Self::config_column_names`]:
+    /// the same declaration that names the positional `columns` slots
+    /// should say what the other view fields draw, so that consumers —
+    /// the settings UI's field labels, and the agent's `list_plugins`
+    /// contract — read one source instead of restating the mapping.
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub group_by_role: Option<String>,
+
+    /// What `split_by` MEANS visually for this plugin, e.g. `"Series"`.
+    /// See [`Self::group_by_role`].
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub split_by_role: Option<String>,
+
+    /// `true` when this plugin CONNECTS its points in row order, so the
+    /// `View`'s row order is visible in the drawing: an unsorted config
+    /// renders the table's natural order, which reads as a tangle unless
+    /// the rows already arrive ordered along the axis. Declared rather
+    /// than inferred, because "unsorted" is not itself a mistake — a
+    /// pre-ordered table needs no `sort`, and the point plugins
+    /// (scatter, density) do not care at all.
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub connects_row_order: bool,
 }
 
 impl PluginStaticConfig {
+    /// The number of leading `columns` slots that are POSITIONAL: a drop
+    /// there swaps with the column already present, and the slot's
+    /// meaning is fixed by [`Self::config_column_names`]. Everything from
+    /// this index on is the insert TAIL, which repeats the last named
+    /// role — which is why a `Y Line` (named slots: `["Y Axis"]`) takes
+    /// any number of columns as additional Y series, while an
+    /// `X/Y Line` (`["X Axis", "Y Axis", "Tooltip"]`) pins its two axes
+    /// and treats the rest as further tooltips.
+    ///
+    /// The single definition of that rule: [`Self::is_swap`] and the
+    /// agent's `list_plugins` contract both derive from it, so the
+    /// convention cannot be read two different ways.
+    pub fn positional_columns(&self) -> usize {
+        self.config_column_names.len().saturating_sub(1)
+    }
+
+    /// The role that `columns` past the positional slots repeat, i.e.
+    /// the last named slot. `None` when the plugin names no slots.
+    pub fn tail_column_role(&self) -> Option<&str> {
+        self.config_column_names.last().map(|x| x.as_str())
+    }
+
     /// `true` if dropping a column at `index` should swap with the
-    /// column already there rather than insert. Only the named slots
-    /// (`config_column_names[..len()-1]`) participate in swap behaviour;
-    /// the trailing unnamed tail inserts.
+    /// column already there rather than insert.
     pub fn is_swap(&self, index: usize) -> bool {
-        !self.config_column_names.is_empty() && index < self.config_column_names.len() - 1
+        !self.config_column_names.is_empty() && index < self.positional_columns()
     }
 
     pub fn get_group_rollups(&self, rollup_features: &[GroupRollupMode]) -> Vec<GroupRollupMode> {
@@ -141,4 +203,57 @@ impl PluginStaticConfig {
             })
             .unwrap_or_default()
     }
+
+    pub fn get_split_rollups(&self, rollup_features: &[SplitRollupMode]) -> Vec<SplitRollupMode> {
+        self.split_rollup_modes
+            .clone()
+            .map(|x| {
+                x.into_iter()
+                    .filter(|y| rollup_features.is_empty() || rollup_features.contains(y))
+                    .collect()
+            })
+            .unwrap_or_default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn plugin(names: &[&str]) -> PluginStaticConfig {
+        PluginStaticConfig {
+            config_column_names: names.iter().map(|x| (*x).to_owned()).collect(),
+            ..Default::default()
+        }
+    }
+
+    /// The tail rule has ONE definition: `is_swap` and the role a
+    /// trailing column repeats must never disagree about where the
+    /// positional slots end.
+    #[test]
+    fn positional_slots_and_tail_agree() {
+        // `Y Line` — the only named slot IS the tail, so every column
+        // is another Y series and none of them swap.
+        let y_line = plugin(&["Y Axis"]);
+        assert_eq!(y_line.positional_columns(), 0);
+        assert_eq!(y_line.tail_column_role(), Some("Y Axis"));
+        assert!(!y_line.is_swap(0));
+
+        // `X/Y Line` — two pinned axes, then tooltips.
+        let xy_line = plugin(&["X Axis", "Y Axis", "Tooltip"]);
+        assert_eq!(xy_line.positional_columns(), 2);
+        assert_eq!(xy_line.tail_column_role(), Some("Tooltip"));
+        assert!(xy_line.is_swap(0));
+        assert!(xy_line.is_swap(1));
+        assert!(!xy_line.is_swap(2));
+
+        for index in 0..4 {
+            assert_eq!(xy_line.is_swap(index), index < xy_line.positional_columns());
+        }
+
+        let unnamed = plugin(&[]);
+        assert_eq!(unnamed.positional_columns(), 0);
+        assert_eq!(unnamed.tail_column_role(), None);
+        assert!(!unnamed.is_swap(0));
+    }
 }