perspective_viewer/
lib.rs

1// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
2// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
3// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
4// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
5// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
6// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
7// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
8// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
9// ┃ This file is part of the Perspective library, distributed under the terms ┃
10// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
11// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
12
13//! The API for the [`@perspective-dev/viewer`](https://perspective-dev.github.io)
14//! JavaScript library.
15
16// Required by yew's `html` macro.
17#![recursion_limit = "1024"]
18#![feature(const_type_name)]
19#![feature(iter_intersperse)]
20#![feature(stmt_expr_attributes)]
21#![feature(try_blocks)]
22#![allow(async_fn_in_trait)]
23#![warn(
24    clippy::all,
25    clippy::panic_in_result_fn,
26    clippy::fallible_impl_from,
27    clippy::unneeded_field_pattern
28)]
29// Holding a `Ref` across an `await` is the sibling footgun of the config
30// write-back race this crate was rearchitected against (see
31// `SESSION_CONFIG_COHERENCE_PLAN.md`) — deny, don't warn.
32#![deny(clippy::await_holding_refcell_ref)]
33
34pub mod components;
35pub mod config;
36pub mod custom_elements;
37mod custom_events;
38pub mod exprtk;
39mod js;
40mod presentation;
41mod root;
42
43#[doc(hidden)]
44pub mod queries;
45mod renderer;
46mod session;
47
48#[doc(hidden)]
49pub mod tasks;
50pub mod utils;
51mod workspace;
52
53#[macro_use]
54extern crate macro_rules_attribute;
55extern crate alloc;
56
57use std::cell::RefCell;
58
59use perspective_js::utils::*;
60use wasm_bindgen::prelude::*;
61
62use crate::custom_elements::copy_dropdown::CopyDropDownMenuElement;
63use crate::custom_elements::debug_plugin::PerspectiveDebugPluginElement;
64use crate::custom_elements::export_dropdown::ExportDropDownMenuElement;
65use crate::custom_elements::viewer::PerspectiveViewerElement;
66use crate::utils::define_web_component;
67
68#[wasm_bindgen(typescript_custom_section)]
69const TS_APPEND_CONTENT: &'static str = r#"
70import type {
71    ColumnType,
72    TableInitOptions,
73    ColumnWindow,
74    ViewWindow,
75    TypedArrayWindow,
76    OnUpdateOptions,
77    JoinOptions,
78    UpdateOptions,
79    DeleteOptions,
80    ViewConfig,
81    ViewConfigUpdate,
82    SystemInfo,
83    Scalar,
84    Features,
85} from "@perspective-dev/client";
86
87export type * from "../../src/ts/ts-rs/ViewerConfig.d.ts";
88export type * from "../../src/ts/ts-rs/ViewerConfigUpdate.d.ts";
89export type * from "../../src/ts/ts-rs/PluginStaticConfig.d.ts";
90export type * from "../../src/ts/ts-rs/WorkspaceConfig.d.ts";
91export type * from "../../src/ts/ts-rs/WorkspaceConfigUpdate.d.ts";
92export type * from "../../src/ts/ts-rs/ExportMethod.d.ts";
93export type * from "../../src/ts/ts-rs/PanelOptions.d.ts";
94export type * from "../../src/ts/ts-rs/ClientOptions.d.ts";
95export type * from "../../src/ts/ts-rs/ExportOptions.d.ts";
96export type * from "../../src/ts/ts-rs/GetTableOptions.d.ts";
97export type * from "../../src/ts/ts-rs/GetClientOptions.d.ts";
98import type {GetTableOptions} from "../../src/ts/ts-rs/GetTableOptions.d.ts";
99import type {PanelOptions} from "../../src/ts/ts-rs/PanelOptions.d.ts";
100import type {ExportOptions} from "../../src/ts/ts-rs/ExportOptions.d.ts";
101import type {GetClientOptions} from "../../src/ts/ts-rs/GetClientOptions.d.ts";
102import type {ClientOptions} from "../../src/ts/ts-rs/ClientOptions.d.ts";
103import type {ViewerConfig} from "../../src/ts/ts-rs/ViewerConfig.d.ts";
104import type {ViewerConfigUpdate} from "../../src/ts/ts-rs/ViewerConfigUpdate.d.ts";
105import type {WorkspaceConfig} from "../../src/ts/ts-rs/WorkspaceConfig.d.ts";
106import type {WorkspaceConfigUpdate} from "../../src/ts/ts-rs/WorkspaceConfigUpdate.d.ts";
107"#;
108
109/// Register a plugin globally.
110#[wasm_bindgen]
111#[allow(non_snake_case)]
112pub fn registerPlugin(name: &str) {
113    use crate::renderer::*;
114    PLUGIN_REGISTRY.register_plugin(name);
115}
116
117/// Register this crate's Custom Elements in the browser's current session.
118///
119/// This must occur before calling any public API methods on these Custom
120/// Elements from JavaScript, as the methods themselves won't be defined yet.
121/// By default, this crate does not register `PerspectiveViewerElement` (as to
122/// preserve backwards-compatible synchronous API).
123#[cfg(not(feature = "external-bootstrap"))]
124#[wasm_bindgen(js_name = "init")]
125pub fn js_init(module: js_sys::WebAssembly::Module, url: web_sys::Url) {
126    console_error_panic_hook::set_once();
127    perspective_js::utils::set_global_logging();
128    define_web_components!("export * as psp from '../../perspective-viewer.js'");
129    MODULE.with_borrow_mut(|f| {
130        *f = Some((module, url));
131    });
132
133    tracing::info!("Perspective initialized.");
134}
135
136thread_local! {
137    static MODULE: RefCell<Option<(js_sys::WebAssembly::Module, web_sys::Url)>> = RefCell::default();
138}
139
140#[cfg(not(feature = "external-bootstrap"))]
141#[wasm_bindgen(js_name = "get_wasm_module")]
142pub fn js_get_module() -> Result<js_sys::WebAssembly::Module, JsValue> {
143    MODULE
144        .with_borrow(|f| f.clone().map(|x| x.0))
145        .ok_or_else(|| "Uninited module".into())
146}
147
148#[cfg(not(feature = "external-bootstrap"))]
149#[wasm_bindgen(js_name = "get_worker_url")]
150pub fn js_get_worker_url() -> Result<web_sys::Url, JsValue> {
151    MODULE
152        .with_borrow(|f| f.clone().map(|x| x.1))
153        .ok_or_else(|| "Uninited module".into())
154}
155
156/// Register Web Components with the global registry, given a Perspective
157/// module.
158///
159/// This function shouldn't be called directly;  instead, use the
160/// `define_web_components!` macro to both call this method and hook the
161/// wasm_bindgen module object.
162pub fn bootstrap_web_components(psp: &JsValue) {
163    define_web_component::<PerspectiveViewerElement>(psp);
164    define_web_component::<PerspectiveDebugPluginElement>(psp);
165    define_web_component::<CopyDropDownMenuElement>(psp);
166    define_web_component::<ExportDropDownMenuElement>(psp);
167}
168
169/// Defining the web components needs an extern struct to reference the
170/// generated JavaSript glue. This is parameterized by an attribute macro which
171/// needs to be determined by the top-level compiled module - the JavaScript
172/// glue code emitted by `wasm-bindgen-cli`.
173#[macro_export]
174macro_rules! define_web_components {
175    ($x:expr) => {{
176        #[wasm_bindgen::prelude::wasm_bindgen(inline_js = $x)]
177        extern "C" {
178            #[wasm_bindgen::prelude::wasm_bindgen(js_name = "psp")]
179            #[wasm_bindgen::prelude::wasm_bindgen(thread_local_v2)]
180            pub static PSP: wasm_bindgen::prelude::JsValue;
181        }
182
183        PSP.with(|x| $crate::bootstrap_web_components(x));
184    }};
185}
perspective_viewer/lib.rs

perspective_viewer/
lib.rs
