@perspective-dev/viewer 4.5.2 → 5.0.0

package/src/rust/renderer/dispatch.rs

@@ -0,0 +1,436 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! The [`Renderer`]'s LOCKED dispatch tier: everything that touches the
+//! active plugin element under the per-renderer draw lock — the
+//! `render_task` pipeline entry, the `draw_fresh`/`update_bound` dispatches,
+//! restyle, resize and the presize protocol.
+
+use std::future::Future;
+use std::rc::Rc;
+
+use perspective_client::View;
+use perspective_js::utils::{ApiResult, ResultTApiErrorExt};
+use wasm_bindgen::prelude::*;
+use web_sys::*;
+
+use super::activate::*;
+use super::limits::*;
+use super::{ContextPin, RenderContext, Renderer, SUBPIXEL_EPSILON};
+use crate::js::plugin::*;
+use crate::session::FreshView;
+use crate::utils::*;
+
+impl Renderer {
+    /// Toggle the `active` and panel-count (`single`/`multi`) classes on
+    /// `plugin`.
+    fn stamp_active(&self, plugin: &JsPerspectiveViewerPlugin) {
+        let el = plugin.unchecked_ref::<HtmlElement>();
+        let _ = el
+            .class_list()
+            .toggle_with_force("active", self.0.is_active_panel.get());
+
+        let is_solo = self.0.is_solo_panel.get();
+        let _ = el.class_list().toggle_with_force("single", is_solo);
+        let _ = el.class_list().toggle_with_force("multi", !is_solo);
+    }
+
+    /// Stamp this panel's effective `theme` attribute.
+    pub fn stamp_theme(&self, plugin: Option<&JsPerspectiveViewerPlugin>) {
+        let active_plugin = self.active_plugin();
+        if let Some(plugin) = plugin.or(active_plugin.as_ref()) {
+            let theme_elem = plugin.unchecked_ref::<HtmlElement>();
+            match self.effective_theme() {
+                Some(theme)
+                    if theme_elem.get_attribute("theme").as_deref() != Some(theme.as_str()) =>
+                {
+                    let _ = theme_elem.set_attribute("theme", &theme);
+                },
+                Some(_) => {},
+                None => {
+                    let _ = theme_elem.remove_attribute("theme");
+                },
+            }
+        }
+    }
+
+    /// Restyle the active plugin and re-draw.
+    pub async fn restyle_all(&self) -> ApiResult<JsValue> {
+        self.render_task(|guard| async move {
+            let Some(ctx) = self.cached_context() else {
+                return Ok(JsValue::UNDEFINED);
+            };
+
+            let _pin = self.pin_context(&guard, ctx.clone());
+            let plugin = self.ensure_plugin_selected()?;
+            let meta = self.metadata();
+            let stamped_theme = self.effective_theme();
+            self.stamp_theme(Some(&plugin));
+            self.stamp_active(&plugin);
+            plugin.restyle();
+            *self.0.captured_theme.borrow_mut() = Some(stamped_theme);
+            let mut limits =
+                get_row_and_col_limits(&ctx.view, &meta, self.is_render_warning_enabled()).await?;
+
+            limits.is_update = true;
+            plugin
+                .update(
+                    ctx.view.clone().into(),
+                    limits.max_cols,
+                    limits.max_rows,
+                    false,
+                )
+                .await?;
+
+            Ok(JsValue::UNDEFINED)
+        })
+        .await
+    }
+
+    pub async fn with_lock<T>(self, task: impl Future<Output = ApiResult<T>>) -> ApiResult<T> {
+        let draw_mutex = self.draw_lock();
+        draw_mutex.lock(task).await
+    }
+
+    /// The [`RenderContext`] pinned by the run currently holding this
+    /// renderer's draw lock, if any. The per-panel element getters answer
+    /// from this when present (invariant I5).
+    pub fn render_context(&self) -> Option<Rc<RenderContext>> {
+        self.0.active_context.borrow().clone()
+    }
+
+    /// The cached [`RenderContext`] of the currently-bound `View` (set by
+    /// the pipeline at bind time).
+    pub fn cached_context(&self) -> Option<Rc<RenderContext>> {
+        self.0.cached_context.borrow().clone()
+    }
+
+    /// Cache `ctx` as the bound view's context (pipeline, at bind time).
+    pub fn set_cached_context(&self, ctx: Rc<RenderContext>) {
+        *self.0.cached_context.borrow_mut() = Some(ctx);
+    }
+
+    /// Pin `ctx` as the active [`RenderContext`] for the duration of the
+    /// returned RAII guard. Requires the lock witness — a context can only
+    /// be pinned by a locked run.
+    pub fn pin_context(&self, _guard: &RenderGuard, ctx: Rc<RenderContext>) -> ContextPin {
+        *self.0.active_context.borrow_mut() = Some(ctx);
+        ContextPin(self.clone())
+    }
+
+    /// `true` while a run is executing on this renderer's draw lock.
+    pub fn is_locked(&self) -> bool {
+        self.draw_lock.is_held()
+    }
+
+    pub async fn resize(&self) -> ApiResult<()> {
+        let draw_mutex = self.draw_lock();
+        let timer = self.render_timer();
+        draw_mutex
+            .debounce_with(|_guard| async move {
+                set_timeout(timer.get_throttle()).await?;
+                let Some(jsplugin) = self.active_plugin() else {
+                    return Ok(());
+                };
+                self.stamp_active(&jsplugin);
+                jsplugin.resize().await?;
+                Ok(())
+            })
+            .await
+    }
+
+    /// Public one-shot resize to explicit dimensions (`viewer.resize({
+    /// dimensions })`).
+    pub async fn resize_with_dimensions(&self, width: f64, height: f64) -> ApiResult<()> {
+        if let Some(present) = self.presize_with_dimensions(width, height).await? {
+            present.call0(&JsValue::NULL)?;
+        }
+
+        Ok(())
+    }
+
+    /// Render every changed pixel of a pending `(width, height)` box.
+    pub async fn presize_with_dimensions(
+        &self,
+        width: f64,
+        height: f64,
+    ) -> ApiResult<Option<js_sys::Function>> {
+        self.0.presize_pending.set(self.0.presize_pending.get() + 1);
+        let result = self.presize_inner(None, width, height).await;
+        self.0.presize_pending.set(self.0.presize_pending.get() - 1);
+        result
+    }
+
+    /// Pre-size AND pre-position the plugin to its target layout bo.
+    pub async fn presize_with_box(
+        &self,
+        dx: f64,
+        dy: f64,
+        width: f64,
+        height: f64,
+    ) -> ApiResult<Option<js_sys::Function>> {
+        self.0.presize_pending.set(self.0.presize_pending.get() + 1);
+        let result = self.presize_inner(Some((dx, dy)), width, height).await;
+        self.0.presize_pending.set(self.0.presize_pending.get() - 1);
+        result
+    }
+
+    async fn presize_inner(
+        &self,
+        translate: Option<(f64, f64)>,
+        width: f64,
+        height: f64,
+    ) -> ApiResult<Option<js_sys::Function>> {
+        let draw_mutex = self.draw_lock();
+        draw_mutex
+            .debounce_with(|_guard| async move {
+                let Some(plugin) = self.active_plugin() else {
+                    return Ok(None);
+                };
+
+                self.stamp_active(&plugin);
+                self.clear_presize()?;
+                let main_panel: &web_sys::HtmlElement = plugin.unchecked_ref();
+                let rect = main_panel.get_bounding_client_rect();
+                let size_changed = (height - rect.height()).abs() > SUBPIXEL_EPSILON
+                    || (width - rect.width()).abs() > SUBPIXEL_EPSILON;
+
+                let (dx, dy) = translate.unwrap_or((0.0, 0.0));
+                let moved = dx.abs() > SUBPIXEL_EPSILON || dy.abs() > SUBPIXEL_EPSILON;
+                if !size_changed && !moved {
+                    return Ok(None);
+                }
+
+                if plugin.capabilities().presize {
+                    if size_changed {
+                        return plugin.presize(width, height).await;
+                    }
+
+                    return Ok(None);
+                }
+
+                if size_changed {
+                    main_panel
+                        .style()
+                        .set_property("width", &format!("{width}px"))?;
+                    main_panel
+                        .style()
+                        .set_property("height", &format!("{height}px"))?;
+                }
+
+                if moved {
+                    main_panel
+                        .style()
+                        .set_property("transform", &format!("translate({dx}px, {dy}px)"))?;
+                }
+
+                if size_changed {
+                    let result = plugin.resize().await;
+                    if translate.is_none() {
+                        main_panel.style().set_property("width", "")?;
+                        main_panel.style().set_property("height", "")?;
+                    }
+
+                    result?;
+                }
+
+                Ok(None)
+            })
+            .await
+    }
+
+    /// Remove the inline presize styles applied by [`Self::presize_with_box`].
+    pub fn clear_presize(&self) -> ApiResult<()> {
+        if let Some(plugin) = self.active_plugin() {
+            let el = plugin.unchecked_ref::<web_sys::HtmlElement>();
+            el.style().set_property("width", "")?;
+            el.style().set_property("height", "")?;
+            el.style().set_property("transform", "")?;
+        }
+
+        Ok(())
+    }
+
+    pub async fn render_task<T, F, Fut>(&self, f: F) -> ApiResult<T>
+    where
+        F: FnOnce(RenderGuard) -> Fut,
+        Fut: Future<Output = ApiResult<T>>,
+    {
+        self.draw_lock().lock_with(f).await
+    }
+
+    /// FULL-draw a NEW `View` on the active plugin (`plugin.draw`).
+    pub async fn draw_fresh(&self, guard: &RenderGuard, view: FreshView) -> ApiResult<()> {
+        let timer = self.render_timer();
+        timer
+            .capture_time(self.draw_view(guard, view.view(), false))
+            .await
+    }
+
+    /// Repaint the ALREADY-BOUND `view` on the active plugin.
+    pub async fn update_bound(&self, guard: &RenderGuard, view: &View) -> ApiResult<()> {
+        let timer = self.render_timer();
+        timer.capture_time(self.draw_view(guard, view, true)).await
+    }
+
+    /// Mint the [`FreshView`] full-draw witness for a plugin that has never
+    /// painted the bound `View`.
+    pub fn promote_first_paint(&self, view: &View) -> Option<FreshView> {
+        if !self.0.has_drawn.get() {
+            Some(FreshView::assert_fresh(view.clone()))
+        } else {
+            None
+        }
+    }
+
+    /// Whether the active plugin's element is currently hidden.
+    pub fn is_plugin_hidden(&self) -> bool {
+        match self.active_plugin() {
+            Some(plugin) => plugin
+                .unchecked_ref::<web_sys::HtmlElement>()
+                .offset_parent()
+                .is_none(),
+            None => false,
+        }
+    }
+
+    /// Record a `table_updated` redraw dropped while hidden (see
+    /// [`RendererData::data_stale`]).
+    pub fn set_data_stale(&self) {
+        self.0.data_stale.set(true);
+    }
+
+    /// Consume the dropped-update marker; the caller owes a full
+    /// `plugin.update` dispatch when `true`.
+    pub fn take_data_stale(&self) -> bool {
+        self.0.data_stale.replace(false)
+    }
+
+    pub async fn activation_repaint(&self, _guard: &RenderGuard) -> ApiResult<()> {
+        if let Some(plugin) = self.active_plugin() {
+            self.stamp_active(&plugin);
+            self.stamp_theme(Some(&plugin));
+            let _ = plugin.resize().await?;
+        }
+
+        Ok(())
+    }
+
+    /// Redraw an already-bound view, debounced.
+    pub async fn update_lazy(
+        &self,
+        view: impl Future<Output = ApiResult<Option<View>>>,
+    ) -> ApiResult<()> {
+        let timer = self.render_timer();
+        self.draw_lock()
+            .debounce_with(|guard| async move {
+                set_timeout(timer.get_throttle()).await?;
+                if self.0.presize_pending.get() > 0 {
+                    tracing::debug!("Update skipped, presize pending");
+                    return Ok(());
+                }
+
+                self.mount_active_plugin()?;
+                if let Some(view) = view.await? {
+                    let _pin = self
+                        .cached_context()
+                        .map(|ctx| self.pin_context(&guard, ctx));
+
+                    let timer = self.render_timer();
+                    timer
+                        .capture_time(self.draw_view(&guard, &view, true))
+                        .await
+                } else {
+                    tracing::debug!("Render skipped, no `View` attached");
+                    Ok(())
+                }
+            })
+            .await
+    }
+
+    async fn draw_view(
+        &self,
+        _guard: &RenderGuard,
+        view: &perspective_client::View,
+        is_update: bool,
+    ) -> ApiResult<()> {
+        debug_assert!(
+            !is_update || self.cached_context().is_none() || self.render_context().is_some(),
+            "I5: RenderContext not pinned at plugin dispatch"
+        );
+
+        let plugin = if is_update {
+            match self.active_plugin() {
+                Some(plugin) => plugin,
+                None => return Ok(()),
+            }
+        } else {
+            self.ensure_plugin_selected()?
+        };
+
+        let meta = self.metadata();
+        let mut limits =
+            get_row_and_col_limits(view, &meta, self.is_render_warning_enabled()).await?;
+
+        limits.is_update = is_update;
+        if let Some(cb) = self.0.on_render_limits_changed.borrow().as_ref() {
+            cb.emit(limits);
+        }
+
+        let viewer_elem = self.0.borrow().viewer_elem.clone();
+        let slot = self.slot_name();
+        let first_paint = !self.0.has_drawn.get();
+        let stamped_theme = self.effective_theme();
+        self.stamp_active(&plugin);
+        self.stamp_theme(Some(&plugin));
+        if self.needs_restyle() {
+            plugin.restyle();
+            *self.0.captured_theme.borrow_mut() = Some(stamped_theme.clone());
+        }
+
+        self.0.data_stale.set(false);
+        let result = if is_update {
+            let task = plugin.update(view.clone().into(), limits.max_cols, limits.max_rows, false);
+            activate_plugin(_guard, &viewer_elem, &plugin, slot.as_deref(), task).await
+        } else {
+            let task = plugin.draw(view.clone().into(), limits.max_cols, limits.max_rows, false);
+            activate_plugin(_guard, &viewer_elem, &plugin, slot.as_deref(), task).await
+        };
+
+        if result.is_ok() {
+            self.0.has_drawn.set(true);
+            if first_paint {
+                *self.0.captured_theme.borrow_mut() = Some(stamped_theme);
+            }
+        }
+
+        let cleanup = remove_inactive_plugin(
+            &viewer_elem,
+            &plugin,
+            slot.as_deref(),
+            self.plugin_data.borrow_mut().plugin_store.plugins(),
+        );
+
+        match result.ignore_view_delete() {
+            Err(error) if !self.0.has_drawn.get() => Err(error),
+            Err(error) => {
+                tracing::warn!("{}", error);
+                cleanup
+            },
+            Ok(_) => cleanup,
+        }
+    }
+
+    fn draw_lock(&self) -> DebounceMutex {
+        self.draw_lock.clone()
+    }
+}