@perspective-dev/viewer 5.5.0 → 5.6.0

package/src/rust/session/panel_state.rs

@@ -0,0 +1,327 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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::rc::Rc;
+
+use perspective_client::config::{ColumnType, Filter, ViewConfig};
+use perspective_client::{Client, Description, Table};
+
+use super::TableErrorState;
+use super::metadata::SessionMetadata;
+
+/// One panel's committed state, as ONE immutable value: a holder of an
+/// `Rc<PanelState>` sees a consistent snapshot forever, and a change is a new
+/// value swapped in whole.
+#[derive(Clone, Default)]
+pub struct PanelState {
+    pub chrome: Chrome,
+    pub binding: Binding,
+
+    /// The element's global filter as broadcast to this panel — the WHOLE set.
+    pub overlay: Rc<Vec<OverlayClause>>,
+}
+
+/// One clause of the element-level global filter, with the type its column has
+/// in the panel that BROADCAST it.
+#[derive(Clone, Debug, PartialEq)]
+pub struct OverlayClause {
+    pub filter: Filter,
+    pub column_type: Option<ColumnType>,
+}
+
+impl From<Filter> for OverlayClause {
+    /// A clause with no broadcaster.
+    fn from(filter: Filter) -> Self {
+        Self {
+            filter,
+            column_type: None,
+        }
+    }
+}
+
+/// The config a `View` is built from: `config`, plus each `overlay` clause the
+/// listening table can honor — one naming a column the listener has, with the
+/// broadcaster's type.
+pub fn effective(
+    config: &ViewConfig,
+    overlay: &[OverlayClause],
+    type_of: &dyn Fn(&str) -> Option<ColumnType>,
+) -> (ViewConfig, Vec<usize>) {
+    let mut effective = config.clone();
+    let mut skipped = Vec::new();
+    for (idx, clause) in overlay.iter().enumerate() {
+        let applies = match (type_of(clause.filter.column()), clause.column_type) {
+            (Some(listener), Some(broadcaster)) => listener == broadcaster,
+            (Some(_), None) => true,
+            (None, _) => false,
+        };
+
+        if applies {
+            effective.filter.push(clause.filter.clone());
+        } else {
+            skipped.push(idx);
+        }
+    }
+
+    (effective, skipped)
+}
+
+/// Panel presentation that is not a function of the data.
+#[derive(Clone, Default)]
+pub struct Chrome {
+    pub title: Option<String>,
+}
+
+/// What this panel is bound to.
+#[derive(Clone)]
+pub enum Binding {
+    /// No table requested.
+    Unbound {
+        client: Option<Client>,
+        config: Rc<ViewConfig>,
+    },
+
+    /// A named table that no client hosts yet; `client` is the one asked.
+    Awaiting {
+        client: Client,
+        name: String,
+        config: Rc<ViewConfig>,
+    },
+
+    /// Bound to `table`.
+    Bound(Rc<BoundState>),
+
+    /// The binding failed or its connection dropped.
+    Lost {
+        prior: Rc<Binding>,
+        error: TableErrorState,
+    },
+}
+
+impl Default for Binding {
+    fn default() -> Self {
+        Self::Unbound {
+            client: None,
+            config: Rc::default(),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct BoundState {
+    pub table: Table,
+    pub metadata: Rc<SessionMetadata>,
+    pub config: Rc<ViewConfig>,
+
+    /// The server's [`Description`] of the last validated effective config,
+    /// keyed by that config.
+    pub description: Option<(Rc<ViewConfig>, Rc<Description>)>,
+}
+
+impl Binding {
+    /// This binding, seen through a [`Binding::Lost`] to what it was.
+    fn live(&self) -> &Binding {
+        match self {
+            Binding::Lost { prior, .. } => prior,
+            binding => binding,
+        }
+    }
+
+    /// `f` applied to the live binding, preserving a `Lost` wrapper.
+    fn map_live(&self, f: impl FnOnce(&Binding) -> Binding) -> Binding {
+        match self {
+            Binding::Lost { prior, error } => Binding::Lost {
+                prior: Rc::new(f(prior)),
+                error: error.clone(),
+            },
+            binding => f(binding),
+        }
+    }
+}
+
+impl PanelState {
+    pub fn config(&self) -> &Rc<ViewConfig> {
+        match self.binding.live() {
+            Binding::Unbound { config, .. } | Binding::Awaiting { config, .. } => config,
+            Binding::Bound(bound) => &bound.config,
+            Binding::Lost { .. } => unreachable!("`Lost::prior` is never `Lost`"),
+        }
+    }
+
+    /// The client this panel is bound through, awaits a table on, or will look
+    /// one up on.
+    pub fn client(&self) -> Option<Client> {
+        match self.binding.live() {
+            Binding::Unbound { client, .. } => client.clone(),
+            Binding::Awaiting { client, .. } => Some(client.clone()),
+            Binding::Bound(bound) => Some(bound.table.get_client()),
+            Binding::Lost { .. } => unreachable!("`Lost::prior` is never `Lost`"),
+        }
+    }
+
+    pub fn bound(&self) -> Option<&Rc<BoundState>> {
+        match self.binding.live() {
+            Binding::Bound(bound) => Some(bound),
+            _ => None,
+        }
+    }
+
+    pub fn awaiting(&self) -> Option<&str> {
+        match self.binding.live() {
+            Binding::Awaiting { name, .. } => Some(name),
+            _ => None,
+        }
+    }
+
+    pub fn lost(&self) -> Option<&TableErrorState> {
+        match &self.binding {
+            Binding::Lost { error, .. } => Some(error),
+            _ => None,
+        }
+    }
+
+    /// This state with its binding lost to `error`.
+    pub fn with_lost(&self, error: TableErrorState) -> Self {
+        Self {
+            binding: Binding::Lost {
+                prior: Rc::new(self.binding.live().clone()),
+                error,
+            },
+            ..self.clone()
+        }
+    }
+
+    /// This state with a lost binding recovered to what it was.
+    pub fn recovered(&self) -> Self {
+        Self {
+            binding: self.binding.live().clone(),
+            ..self.clone()
+        }
+    }
+
+    /// This state with `config` in place of its view config.
+    pub fn with_config(&self, config: Rc<ViewConfig>) -> Self {
+        let binding = self.binding.map_live(|binding| match binding {
+            Binding::Unbound { client, .. } => Binding::Unbound {
+                client: client.clone(),
+                config,
+            },
+            Binding::Awaiting { client, name, .. } => Binding::Awaiting {
+                client: client.clone(),
+                name: name.clone(),
+                config,
+            },
+            Binding::Bound(bound) => Binding::Bound(Rc::new(BoundState {
+                config,
+                description: None,
+                ..(**bound).clone()
+            })),
+            Binding::Lost { .. } => unreachable!("`Lost::prior` is never `Lost`"),
+        });
+
+        Self {
+            binding,
+            ..self.clone()
+        }
+    }
+
+    /// This state with nothing bound and nothing awaited (a lost binding is
+    /// replaced, not recovered); the client and config are kept.
+    pub fn unbound(&self) -> Self {
+        self.unbound_on(self.client())
+    }
+
+    /// This state with nothing bound, looking tables up on `client`.
+    pub fn unbound_on(&self, client: Option<Client>) -> Self {
+        Self {
+            binding: Binding::Unbound {
+                client,
+                config: self.config().clone(),
+            },
+            ..self.clone()
+        }
+    }
+
+    /// This state awaiting a host for `name` on `client`; the config is kept.
+    pub fn awaiting_table(&self, client: Client, name: String) -> Self {
+        Self {
+            binding: Binding::Awaiting {
+                client,
+                name,
+                config: self.config().clone(),
+            },
+            ..self.clone()
+        }
+    }
+
+    /// This state with `overlay` broadcast to it.
+    pub fn with_overlay(&self, overlay: Rc<Vec<OverlayClause>>) -> Self {
+        Self {
+            overlay,
+            ..self.with_description(None)
+        }
+    }
+
+    /// This state bound to `table`; the config is kept and nothing has been
+    /// described against the new table yet.
+    pub fn bound_to(&self, table: Table, metadata: SessionMetadata) -> Self {
+        Self {
+            binding: Binding::Bound(Rc::new(BoundState {
+                table,
+                metadata: Rc::new(metadata),
+                config: self.config().clone(),
+                description: None,
+            })),
+            ..self.clone()
+        }
+    }
+
+    /// This state with `metadata` in place of its table metadata; a no-op
+    /// unless bound.
+    pub fn with_metadata(&self, metadata: Rc<SessionMetadata>) -> Self {
+        let binding = self.binding.map_live(|binding| match binding {
+            Binding::Bound(bound) => Binding::Bound(Rc::new(BoundState {
+                metadata,
+                ..(**bound).clone()
+            })),
+            binding => binding.clone(),
+        });
+
+        Self {
+            binding,
+            ..self.clone()
+        }
+    }
+
+    /// This state with `description` recorded; a no-op unless bound.
+    pub fn with_description(&self, description: Option<(Rc<ViewConfig>, Rc<Description>)>) -> Self {
+        let binding = self.binding.map_live(|binding| match binding {
+            Binding::Bound(bound) => Binding::Bound(Rc::new(BoundState {
+                description,
+                ..(**bound).clone()
+            })),
+            binding => binding.clone(),
+        });
+
+        Self {
+            binding,
+            ..self.clone()
+        }
+    }
+
+    pub fn with_title(&self, title: Option<String>) -> Self {
+        Self {
+            chrome: Chrome { title },
+            ..self.clone()
+        }
+    }
+}

package/src/rust/session/view_subscription.rs

@@ -43,6 +43,11 @@ struct ViewSubscriptionData {
     on_update: Option<Callback<()>>,
     is_deleted: Rc<Cell<bool>>,
 
+    /// Set by [`ViewSubscription::quiesce`]: the engine registration is gone
+    /// and BOTH emit channels are dead, including any update already in
+    /// flight when the flag flipped.
+    quiesced: Rc<Cell<bool>>,
+
     /// The bound `View`'s latest known dimensions, written before
     /// `on_update`/`on_stats` fire.
     dimensions: Rc<RefCell<Option<ViewDimensionsResp>>>,
@@ -57,8 +62,14 @@ pub struct ViewSubscription {
 impl ViewSubscriptionData {
     /// Main handler when underlying `View()` calls `on_update()`.
     async fn on_view_update(self) -> ApiResult<JsValue> {
+        if self.quiesced.get() {
+            return Ok(JsValue::UNDEFINED);
+        }
+
         self.clone().update_view_stats().await?;
-        if let Some(on_update) = &self.on_update {
+        if let Some(on_update) = &self.on_update
+            && !self.quiesced.get()
+        {
             on_update.emit(());
         };
 
@@ -66,6 +77,10 @@ impl ViewSubscriptionData {
     }
 
     async fn update_view_stats(self) -> ApiResult<JsValue> {
+        if self.quiesced.get() {
+            return Ok(JsValue::UNDEFINED);
+        }
+
         let dimensions = self.view.dimensions().await?;
         let num_rows = dimensions.num_table_rows;
         let num_cols = dimensions.num_table_columns;
@@ -80,7 +95,10 @@ impl ViewSubscriptionData {
             is_split_by: !self.config.split_by.is_empty(),
         };
 
-        self.on_stats.emit(stats);
+        if !self.quiesced.get() {
+            self.on_stats.emit(stats);
+        }
+
         Ok(JsValue::UNDEFINED)
     }
 
@@ -90,7 +108,7 @@ impl ViewSubscriptionData {
         }
 
         let view = &self.view;
-        if self.on_update.is_some() {
+        if self.on_update.is_some() && !self.quiesced.get() {
             view.remove_update(self.callback_id.get()).await?;
         }
 
@@ -125,6 +143,7 @@ impl ViewSubscription {
             callback_id: Rc::default(),
             on_update,
             is_deleted: Rc::default(),
+            quiesced: Rc::default(),
             dimensions: Rc::default(),
         };
 
@@ -191,6 +210,26 @@ impl ViewSubscription {
         self.data.build_config.clone()
     }
 
+    /// Permanently detach this subscription from its `Session` — the engine
+    /// `on_update` registration removed and both emit channels silenced
+    /// (in-flight updates included) — leaving a bare keep-alive handle for a
+    /// `View` that now feeds a derived `Table` rather than this panel.
+    pub async fn quiesce(&self) -> ApiResult<()> {
+        if self.data.quiesced.get() {
+            return Ok(());
+        }
+
+        if self.data.on_update.is_some() {
+            self.data
+                .view
+                .remove_update(self.data.callback_id.get())
+                .await?;
+        }
+
+        self.data.quiesced.set(true);
+        Ok(())
+    }
+
     /// Delete this `View`. Neglecting to call this method before a
     /// `ViewSubscription` is dropped will result in a log warning, but the
     /// `View` will not leak.