@perspective-dev/viewer 4.4.1 → 4.5.1

package/src/rust/components/viewer.rs

@@ -14,22 +14,24 @@ use std::rc::Rc;
 
 use futures::channel::oneshot::*;
 use perspective_js::utils::*;
+use wasm_bindgen::JsCast;
 use wasm_bindgen::prelude::*;
+use web_sys::{FocusEvent, KeyboardEvent};
 use yew::prelude::*;
 
 use super::containers::split_panel::SplitPanel;
 use super::font_loader::{FontLoader, FontLoaderProps, FontLoaderStatus};
-use super::form::debug::DebugPanel;
 use super::style::{LocalStyle, StyleProvider};
 use crate::components::column_settings_sidebar::ColumnSettingsPanel;
 use crate::components::main_panel::MainPanel;
-use crate::components::settings_panel::SettingsPanel;
+use crate::components::settings_panel::{SelectedTab, SettingsPanel};
 use crate::config::*;
 use crate::css;
-use crate::custom_events::CustomEvents;
-use crate::dragdrop::{DragDropProps, *};
 use crate::js::JsPerspectiveViewerPlugin;
-use crate::presentation::{ColumnLocator, ColumnSettingsTab, Presentation, PresentationProps};
+use crate::presentation::{
+    ColumnLocator, ColumnSettingsTab, DragDropProps, Presentation, PresentationProps,
+};
+use crate::queries::*;
 use crate::renderer::{RendererProps, *};
 use crate::session::{SessionProps, *};
 use crate::tasks::*;
@@ -41,8 +43,6 @@ pub struct PerspectiveViewerProps {
     pub elem: web_sys::HtmlElement,
 
     /// State
-    pub custom_events: CustomEvents,
-    pub dragdrop: DragDrop,
     pub session: Session,
     pub renderer: Renderer,
     pub presentation: Presentation,
@@ -54,44 +54,6 @@ impl PartialEq for PerspectiveViewerProps {
     }
 }
 
-impl HasCustomEvents for PerspectiveViewerProps {
-    fn custom_events(&self) -> &CustomEvents {
-        &self.custom_events
-    }
-}
-
-impl HasDragDrop for PerspectiveViewerProps {
-    fn dragdrop(&self) -> &DragDrop {
-        &self.dragdrop
-    }
-}
-
-impl HasPresentation for PerspectiveViewerProps {
-    fn presentation(&self) -> &Presentation {
-        &self.presentation
-    }
-}
-
-impl HasRenderer for PerspectiveViewerProps {
-    fn renderer(&self) -> &Renderer {
-        &self.renderer
-    }
-}
-
-impl HasSession for PerspectiveViewerProps {
-    fn session(&self) -> &Session {
-        &self.session
-    }
-}
-
-impl StateProvider for PerspectiveViewerProps {
-    type State = PerspectiveViewerProps;
-
-    fn clone_state(&self) -> Self::State {
-        self.clone()
-    }
-}
-
 #[derive(Debug)]
 pub enum PerspectiveViewerMsg {
     ColumnSettingsPanelSizeUpdate(Option<i32>),
@@ -105,6 +67,8 @@ pub enum PerspectiveViewerMsg {
     Reset(bool, Option<Sender<()>>),
     Resize,
     SettingsPanelSizeUpdate(Option<i32>),
+    SettingsPanelTabChanged(SelectedTab),
+    SettingsPanelAutoWidth(f64),
     ToggleDebug,
     ToggleSettingsComplete(SettingsUpdate, Sender<()>),
     ToggleSettingsInit(Option<SettingsUpdate>, Option<Sender<ApiResult<JsValue>>>),
@@ -142,8 +106,11 @@ pub struct PerspectiveViewer {
     on_close_column_settings: Callback<()>,
     on_rendered: Option<Sender<()>>,
     on_resize: Rc<PubSub<()>>,
+    on_settings_panel_dimensions_reset: Rc<PubSub<()>>,
     settings_open: bool,
     settings_panel_width_override: Option<i32>,
+    settings_panel_selected_tab: SelectedTab,
+    settings_panel_auto_width: f64,
 
     /// Value-semantic state snapshots (Step 4 scaffold).
     /// Populated by `UpdateSession` / `UpdateRenderer` / `UpdatePresentation` /
@@ -156,6 +123,70 @@ pub struct PerspectiveViewer {
     /// Counts in-flight renders (incremented on `view_config_changed`,
     /// decremented on `view_created`). Threaded to `StatusIndicator`.
     update_count: u32,
+
+    /// Window listeners that toggle the `.shift-active` class on the host
+    /// element while the Shift key is held, making Shift-modified affordances
+    /// (e.g. inactive column add, active column remove, status-bar reset)
+    /// visually discoverable. Stored so the closures outlive `create`.
+    _shift_listeners: ShiftListeners,
+}
+
+struct ShiftListeners {
+    elem: web_sys::HtmlElement,
+    keydown: Closure<dyn FnMut(KeyboardEvent)>,
+    keyup: Closure<dyn FnMut(KeyboardEvent)>,
+    blur: Closure<dyn FnMut(FocusEvent)>,
+}
+
+impl Drop for ShiftListeners {
+    fn drop(&mut self) {
+        let win = global::window();
+        let _ = win
+            .remove_event_listener_with_callback("keydown", self.keydown.as_ref().unchecked_ref());
+        let _ =
+            win.remove_event_listener_with_callback("keyup", self.keyup.as_ref().unchecked_ref());
+        let _ = win.remove_event_listener_with_callback("blur", self.blur.as_ref().unchecked_ref());
+        let _ = self.elem.class_list().remove_1("shift-active");
+    }
+}
+
+fn install_shift_listeners(elem: web_sys::HtmlElement) -> ShiftListeners {
+    let keydown = {
+        let elem = elem.clone();
+        Closure::wrap(Box::new(move |event: KeyboardEvent| {
+            if event.key() == "Shift" {
+                let _ = elem.class_list().add_1("shift-active");
+            }
+        }) as Box<dyn FnMut(KeyboardEvent)>)
+    };
+
+    let keyup = {
+        let elem = elem.clone();
+        Closure::wrap(Box::new(move |event: KeyboardEvent| {
+            if event.key() == "Shift" {
+                let _ = elem.class_list().remove_1("shift-active");
+            }
+        }) as Box<dyn FnMut(KeyboardEvent)>)
+    };
+
+    let blur = {
+        let elem = elem.clone();
+        Closure::wrap(Box::new(move |_: FocusEvent| {
+            let _ = elem.class_list().remove_1("shift-active");
+        }) as Box<dyn FnMut(FocusEvent)>)
+    };
+
+    let win = global::window();
+    let _ = win.add_event_listener_with_callback("keydown", keydown.as_ref().unchecked_ref());
+    let _ = win.add_event_listener_with_callback("keyup", keyup.as_ref().unchecked_ref());
+    let _ = win.add_event_listener_with_callback("blur", blur.as_ref().unchecked_ref());
+
+    ShiftListeners {
+        elem,
+        keydown,
+        keyup,
+        blur,
+    }
 }
 
 impl Component for PerspectiveViewer {
@@ -195,6 +226,8 @@ impl Component for PerspectiveViewer {
             });
         }
 
+        let shift_listeners = install_shift_listeners(elem);
+
         Self {
             _subscriptions: subscriptions,
             column_settings_panel_width_override: None,
@@ -203,13 +236,17 @@ impl Component for PerspectiveViewer {
             on_close_column_settings,
             on_rendered: None,
             on_resize: Default::default(),
+            on_settings_panel_dimensions_reset: Default::default(),
             settings_open: false,
             settings_panel_width_override: None,
+            settings_panel_selected_tab: SelectedTab::default(),
+            settings_panel_auto_width: 0.0,
             session_props,
             renderer_props,
             presentation_props,
             dragdrop_props: DragDropProps::default(),
             update_count: 0,
+            _shift_listeners: shift_listeners,
         }
     }
 
@@ -221,43 +258,13 @@ impl Component for PerspectiveViewer {
                 false
             },
             Reset(all, sender) => {
-                ctx.props().presentation.set_open_column_settings(None);
-                clone!(
-                    ctx.props().renderer,
-                    ctx.props().session,
-                    ctx.props().presentation
+                reset_all(
+                    &ctx.props().session,
+                    &ctx.props().renderer,
+                    &ctx.props().presentation,
+                    all,
+                    sender,
                 );
-
-                ApiFuture::spawn(async move {
-                    session
-                        .reset(ResetOptions {
-                            config: true,
-                            expressions: all,
-                            ..ResetOptions::default()
-                        })
-                        .await?;
-                    let columns_config = if all {
-                        presentation.reset_columns_configs();
-                        None
-                    } else {
-                        Some(presentation.all_columns_configs())
-                    };
-
-                    renderer.reset(columns_config.as_ref()).await?;
-                    presentation.reset_available_themes(None).await;
-                    if all {
-                        presentation.reset_theme().await?;
-                    }
-
-                    let result = renderer.draw(session.validate().await?.create_view()).await;
-                    if let Some(sender) = sender {
-                        sender.send(()).unwrap();
-                    }
-
-                    renderer.reset_changed.emit(());
-                    result
-                });
-
                 false
             },
             ToggleSettingsInit(Some(SettingsUpdate::Missing), None) => false,
@@ -335,6 +342,10 @@ impl Component for PerspectiveViewer {
                     ctx.props()
                         .presentation
                         .set_open_column_settings(Some(open_column_settings));
+
+                    if locator.is_some() {
+                        self.settings_panel_selected_tab = SelectedTab::Query;
+                    }
                 }
 
                 if let Some(sender) = sender {
@@ -349,7 +360,22 @@ impl Component for PerspectiveViewer {
             },
             SettingsPanelSizeUpdate(None) => {
                 self.settings_panel_width_override = None;
-                false
+                self.settings_panel_auto_width = 0.0;
+                self.on_settings_panel_dimensions_reset.emit(());
+                true
+            },
+            SettingsPanelTabChanged(tab) => {
+                let changed = tab != self.settings_panel_selected_tab;
+                self.settings_panel_selected_tab = tab;
+                changed
+            },
+            SettingsPanelAutoWidth(w) => {
+                if w > self.settings_panel_auto_width {
+                    self.settings_panel_auto_width = w;
+                    true
+                } else {
+                    false
+                }
             },
             ColumnSettingsPanelSizeUpdate(Some(x)) => {
                 self.column_settings_panel_width_override = Some(x);
@@ -449,8 +475,6 @@ impl Component for PerspectiveViewer {
 
     fn view(&self, ctx: &Context<Self>) -> Html {
         let Self::Properties {
-            custom_events,
-            dragdrop,
             presentation,
             renderer,
             session,
@@ -470,7 +494,7 @@ impl Component for PerspectiveViewer {
         }
 
         let on_open_expr_panel = ctx.link().callback(|c| OpenColumnSettings {
-            locator: Some(c),
+            locator: c,
             sender: None,
             toggle: true,
         });
@@ -496,17 +520,13 @@ impl Component for PerspectiveViewer {
         let plugin_name = self.renderer_props.plugin_name.clone();
         let available_plugins = self.renderer_props.available_plugins.clone();
         let has_table = self.session_props.has_table.clone();
-        let named_column_count = self
-            .renderer_props
-            .requirements
-            .names
-            .as_ref()
-            .map(|n| n.len())
-            .unwrap_or(0);
+        let named_column_count = self.renderer_props.config.config_column_names.len();
 
         let view_config = self.session_props.config.clone();
         let drag_column = self.dragdrop_props.column.clone();
         let metadata = self.session_props.metadata.clone();
+        let on_select_tab = ctx.link().callback(SettingsPanelTabChanged);
+        let on_auto_width = ctx.link().callback(SettingsPanelAutoWidth);
         let settings_panel = html! {
             if is_settings_open {
                 <SettingsPanel
@@ -520,11 +540,16 @@ impl Component for PerspectiveViewer {
                     {has_table}
                     {named_column_count}
                     {view_config}
+                    plugin_config={self.renderer_props.plugin_config.clone()}
                     {drag_column}
                     metadata={metadata.clone()}
                     open_column_settings={self.presentation_props.open_column_settings.clone()}
                     selected_theme={self.presentation_props.selected_theme.clone()}
-                    {dragdrop}
+                    selected_tab={self.settings_panel_selected_tab}
+                    auto_width={self.settings_panel_auto_width}
+                    on_dimensions_reset={&self.on_settings_panel_dimensions_reset}
+                    {on_select_tab}
+                    {on_auto_width}
                     {presentation}
                     {renderer}
                     {session}
@@ -552,8 +577,8 @@ impl Component for PerspectiveViewer {
                         plugin_name={self.renderer_props.plugin_name.clone()}
                         {metadata}
                         view_config={self.session_props.config.clone()}
+                        column_stats={self.session_props.column_stats.clone()}
                         selected_theme={self.presentation_props.selected_theme.clone()}
-                        {custom_events}
                         {presentation}
                         {renderer}
                         {session}
@@ -564,43 +589,23 @@ impl Component for PerspectiveViewer {
         };
 
         let on_reset = ctx.link().callback(|all| Reset(all, None));
-        let render_limits = self.renderer_props.render_limits;
-        let has_table = self.session_props.has_table.clone();
-        let is_errored = self.session_props.error.is_some();
-        let stats = self.session_props.stats.clone();
-        let update_count = self.update_count;
-        let error = self.session_props.error.clone();
         let is_settings_open = self.settings_open
             && matches!(self.session_props.has_table, Some(TableLoadState::Loaded));
-        let title = self.session_props.title.clone();
-        let selected_theme = self.presentation_props.selected_theme.clone();
-        let available_themes = self.presentation_props.available_themes.clone();
         let main_panel = html! {
             <MainPanel
                 {on_settings}
                 {on_reset}
-                {render_limits}
-                {has_table}
-                {is_errored}
-                {stats}
-                {update_count}
-                {error}
+                session_props={self.session_props.clone()}
+                renderer_props={self.renderer_props.clone()}
+                presentation_props={self.presentation_props.clone()}
                 {is_settings_open}
-                {title}
-                {selected_theme}
-                {available_themes}
-                is_workspace={self.presentation_props.is_workspace}
-                {custom_events}
+                update_count={self.update_count}
                 {presentation}
                 {renderer}
                 {session}
             />
         };
 
-        let debug_panel = html! {
-            if self.debug_open { <DebugPanel {presentation} {renderer} {session} /> }
-        };
-
         html! {
             <StyleProvider root={ctx.props().elem.clone()}>
                 <LocalStyle href={css!("viewer")} />
@@ -612,10 +617,16 @@ impl Component for PerspectiveViewer {
                             skip_empty=true
                             initial_size={self.settings_panel_width_override}
                             on_reset={ctx.link().callback(|_| SettingsPanelSizeUpdate(None))}
-                            on_resize={on_split_panel_resize.clone()}
-                            on_resize_finished={ctx.props().render_callback()}
+                            on_resize={{
+                                let size_cb = on_split_panel_resize.clone();
+                                let resize_cb = resize_callback(&ctx.props().session, &ctx.props().renderer);
+                                move |x| {
+                                    size_cb.emit(x);
+                                    resize_cb.emit(());
+                                }
+                            }}
+                            on_resize_finished={resize_callback(&ctx.props().session, &ctx.props().renderer)}
                         >
-                            { debug_panel }
                             { settings_panel }
                             <div id="main_column_container">
                                 { main_panel }
@@ -735,17 +746,43 @@ fn create_subscriptions(ctx: &Context<PerspectiveViewer>) -> Vec<Subscription> {
             .view_created
             .add_listener(ctx.link().callback(|_| DecrementUpdateCount));
 
-        vec![sub1, sub2, sub3, sub4, sub5, sub6, sub7]
+        // Stats fetch resolution (populates session.column_stats) triggers
+        // a fresh `SessionProps` so `column_stats` reaches downstream
+        // components and the StyleTab re-queries the schema with the
+        // new value.
+        let sub8 = s.column_stats_changed.add_notify_listener(&cb);
+
+        vec![sub1, sub2, sub3, sub4, sub5, sub6, sub7, sub8]
     };
 
     let renderer_props_sub = {
         let renderer = ctx.props().renderer.clone();
         let cb_plugin = ctx.link().callback({
+            let renderer = renderer.clone();
             move |_: JsPerspectiveViewerPlugin| UpdateRenderer(Box::new(renderer.to_props(None)))
         });
 
+        // Re-snapshot RendererProps when the plugin_config bucket
+        // changes (in-tab edit via `send_plugin_config`, JSON paste via
+        // `restore_and_render`, full clear via `reset_all` with
+        // `all=true`). Without this, `RendererProps.plugin_config`
+        // would stay frozen at its construct-time value and `PluginTab`
+        // would render stale.
+        let cb_plugin_config = ctx.link().callback({
+            let renderer = renderer.clone();
+            move |_: serde_json::Map<String, serde_json::Value>| {
+                UpdateRenderer(Box::new(renderer.to_props(None)))
+            }
+        });
+
         let sub1 = ctx.props().renderer.plugin_changed.add_listener(cb_plugin);
-        vec![sub1]
+        let sub2 = ctx
+            .props()
+            .renderer
+            .plugin_config_changed
+            .add_listener(cb_plugin_config);
+
+        vec![sub1, sub2]
     };
 
     let presentation_props_sub = {
@@ -779,7 +816,7 @@ fn create_subscriptions(ctx: &Context<PerspectiveViewer>) -> Vec<Subscription> {
         let cb_clear = ctx.link().callback(|_: ()| UpdateDragDrop(Box::default()));
         let sub1 = ctx
             .props()
-            .dragdrop
+            .presentation
             .drop_received
             .add_notify_listener(&cb_clear);
 
@@ -858,19 +895,19 @@ fn inject_engine_callbacks(ctx: &Context<PerspectiveViewer>) {
             .borrow_mut() = Some(cb);
     }
 
-    // DragDrop: on_dragstart
+    // Drag/drop: on_dragstart (post-merge: lives on Presentation)
     {
-        let dragdrop = ctx.props().dragdrop.clone();
-        let cb = ctx
-            .link()
-            .callback(move |_: DragEffect| UpdateDragDrop(Box::new(dragdrop.to_props())));
+        let presentation = ctx.props().presentation.clone();
+        let cb = ctx.link().callback(move |_: DragEffect| {
+            UpdateDragDrop(Box::new(presentation.drag_drop_props()))
+        });
 
-        *ctx.props().dragdrop.on_dragstart.borrow_mut() = Some(cb);
+        *ctx.props().presentation.on_dragstart.borrow_mut() = Some(cb);
     }
 
-    // DragDrop: on_dragend
+    // Drag/drop: on_dragend
     {
         let cb = ctx.link().callback(|_: ()| UpdateDragDrop(Box::default()));
-        *ctx.props().dragdrop.on_dragend.borrow_mut() = Some(cb);
+        *ctx.props().presentation.on_dragend.borrow_mut() = Some(cb);
     }
 }

package/src/rust/config/column_config_schema.rs

@@ -0,0 +1,195 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use std::collections::HashSet;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use super::{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>,
+}
+
+impl ColumnConfigSchema {
+    /// Union of every JSON key any control in this schema knows how to
+    /// read or write. Used to build the schema-filtered view of
+    /// `columns_config` passed to `plugin.restore()` — keys not in this
+    /// set are "ghost" state from a different plugin and stay invisible
+    /// to the active one.
+    pub fn active_keys(&self) -> HashSet<String> {
+        let mut out = HashSet::new();
+        for spec in &self.fields {
+            for k in spec.serialized_keys() {
+                out.insert(k.to_string());
+            }
+        }
+        out
+    }
+}
+
+/// Discriminated union of widget kinds the viewer can render. Composite
+/// variants wrap an existing rich Yew component and carry only the
+/// component's `*DefaultConfig`. Primitive variants render generic scalar
+/// widgets and carry their own `key` inline; the visible label is
+/// resolved at CSS time via `--psp-label--<key>--content`.
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(tag = "kind")]
+pub enum ControlSpec {
+    Enum {
+        key: String,
+        variants: Vec<EnumVariant>,
+        default: String,
+    },
+    Bool {
+        key: String,
+        default: bool,
+    },
+    Number {
+        key: String,
+        default: f64,
+
+        /// If `true`, always serialize this values even if it is the default.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        include: Option<bool>,
+
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        min: Option<f64>,
+
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        max: Option<f64>,
+
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        step: Option<f64>,
+    },
+    String {
+        key: String,
+        default: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        placeholder: Option<String>,
+    },
+    Color {
+        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,
+    },
+
+    /// 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.
+    StringFormat,
+    NumberSeriesStyle {
+        default: NumberSeriesStyleDefaultConfig,
+    },
+    Symbols {
+        default: KeyValueOpts,
+    },
+    NumberFormat,
+    AggregateDepth,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+pub struct EnumVariant {
+    pub value: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub label: Option<String>,
+}
+
+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]`;
+    /// for composites it's the set of fields the wrapped sub-struct
+    /// flattens. Used by [`ColumnConfigSchema::active_keys`] to filter the
+    /// `columns_config` blob passed to `plugin.restore()`.
+    pub fn serialized_keys(&self) -> Vec<&str> {
+        match self {
+            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::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()],
+        }
+    }
+}
+
+/// One UI-emitted change to a single schema field. The emitting widget
+/// 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>,
+    pub value: serde_json::Map<String, Value>,
+}
+
+/// Filter a per-column config map to only the keys advertised by the
+/// active plugin's schema. Foreign keys (left over from a previous plugin)
+/// stay in the unfiltered presentation state but never reach `restore()`.
+pub fn filter_to_schema(
+    config: &serde_json::Map<String, Value>,
+    active_keys: &HashSet<String>,
+) -> serde_json::Map<String, Value> {
+    config
+        .iter()
+        .filter(|(k, _)| active_keys.contains(k.as_str()))
+        .map(|(k, v)| (k.clone(), v.clone()))
+        .collect()
+}