or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-element.mdevents.mdindex.mdplugin-development.mdwasm-init.md
tile.json

index.mddocs/

Perspective Viewer

Perspective Viewer provides the <perspective-viewer> Custom Element, a framework-agnostic user interface component for interactive analytics and data visualization. Built with WebAssembly (compiled from Rust) for high performance, it serves as the frontend for Perspective.js - a streaming query engine optimized for large and/or streaming datasets.

Package Information

  • Package Name: @finos/perspective-viewer
  • Package Type: npm
  • Language: TypeScript/Rust (WebAssembly)
  • Installation: npm install @finos/perspective-viewer

Core Imports

import "@finos/perspective-viewer";

For manual initialization:

import { init_client } from "@finos/perspective-viewer";

For manual initialization (alternative syntax):

import perspectiveViewer from "@finos/perspective-viewer";
// Use: await perspectiveViewer.init_client(wasmBinary);

For plugin development:

import { 
  IPerspectiveViewerPlugin, 
  HTMLPerspectiveViewerPluginElement,
  HTMLPerspectiveViewerElement 
} from "@finos/perspective-viewer";

For advanced type usage:

import { 
  ViewerConfigUpdate,
  PerspectiveClickEventDetail,
  PerspectiveSelectEventDetail,
  ColumnConfigValues,
  Filter,
  Sort
} from "@finos/perspective-viewer";

Basic Usage

import "@finos/perspective-viewer";
import perspective from "@finos/perspective";

// Create perspective viewer element
const viewer = document.createElement("perspective-viewer");
document.body.appendChild(viewer);

// Load data
const table = await perspective.table({
  name: ["Alice", "Bob", "Charlie"],
  age: [25, 30, 35],
  city: ["NY", "LA", "Chicago"]
});

await viewer.load(table);

// Configure the view
await viewer.restore({
  plugin: "d3_y_bar",
  group_by: ["city"],
  columns: ["age"]
});

Architecture

Perspective Viewer is built around several key components:

  • Custom Element: <perspective-viewer> Web Component with async API methods
  • WebAssembly Core: High-performance Rust backend compiled to WASM for data processing
  • Plugin System: Extensible visualization plugins with standardized interface
  • Configuration System: Comprehensive state management for views, filters, and styling
  • Event System: Custom events for user interactions and configuration changes
  • Lifecycle Management: Proper resource cleanup and memory management for WASM

Capabilities

Core Viewer Element

Main <perspective-viewer> custom element providing all data visualization and interaction functionality.

interface HTMLPerspectiveViewerElement extends HTMLElement {
  // Data Management  
  load(table: Promise<Table> | Table): Promise<void>;
  getTable(wait_for_table?: boolean): Promise<Table>;
  getView(): Promise<View>;
  
  // Configuration & State
  save(format?: "json" | "string" | "arraybuffer"): Promise<ViewerConfig>;
  restore(config: ViewerConfig): Promise<void>;
  reset(reset_all?: boolean): Promise<void>;
  
  // Rendering & Display
  flush(): Promise<void>;
  resize(force?: boolean): Promise<void>;
  
  // Lifecycle
  delete(): Promise<void>;
  eject(): Promise<void>;
}

Core Viewer Element

Plugin Development

Interface and base class for creating custom visualization plugins.

interface IPerspectiveViewerPlugin {
  readonly name: string;
  readonly select_mode?: string;
  readonly min_config_columns?: number;
  readonly priority?: number;
  
  draw(view: View): Promise<void>;
  update(view: View): Promise<void>;
  clear(): Promise<void>;
  resize(): Promise<void>;
  save(): Promise<any>;
  restore(config: any): Promise<void>;
  delete(): Promise<void>;
}

class HTMLPerspectiveViewerPluginElement extends HTMLElement 
  implements IPerspectiveViewerPlugin {
  // Base implementation with default behaviors
}

Plugin Development

Configuration System

Complete configuration interface for viewer state management.

interface ViewerConfigUpdate {
  version?: string | null;
  plugin?: string | null;
  title?: string | null;
  theme?: string | null;
  settings?: boolean | null;
  plugin_config?: any | null;
  columns_config?: Record<string, ColumnConfigValues> | null;
  
  // View configuration
  group_by?: Array<string> | null;
  split_by?: Array<string> | null; 
  columns?: Array<string | null> | null;
  filter?: Array<Filter> | null;
  sort?: Array<Sort> | null;
  expressions?: Record<string, string> | null;
  aggregates?: Record<string, Aggregate> | null;
}

Configuration System

Event System

Custom events for user interactions and configuration changes.

// Event listener registration
viewer.addEventListener("perspective-config-update", (e: CustomEvent) => {
  const config: ViewerConfigUpdate = e.detail;
});

viewer.addEventListener("perspective-select", (e: CustomEvent) => {
  const selection: { view_window: ViewWindow } = e.detail;
});

Event System

WebAssembly Initialization

Manual WebAssembly initialization for advanced use cases.

function init_client(
  wasm_binary: Promise<Response | ArrayBuffer | Uint8Array> 
    | Response 
    | ArrayBuffer 
    | Uint8Array
): Promise<void>;

WebAssembly Initialization

Core Types

type Filter = [string, string, FilterTerm];
type FilterTerm = Array<Scalar> | Scalar;
type FilterReducer = "and" | "or";
type Scalar = number | string | boolean | null;

interface ColumnConfigValues {
  symbols?: Record<string, string>;
  datagrid_number_style?: NumberColumnStyleConfig;
  datagrid_string_style?: StringColumnStyleConfig;
  datagrid_datetime_style?: DatetimeColumnStyleConfig;
  number_format?: CustomNumberFormatConfig | null;
  aggregate_depth?: number;
}

interface ViewWindow {
  start_row: number;
  end_row: number;
  start_col: number;  
  end_col: number;
}

interface PerspectiveClickEventDetail {
  config: ViewerConfigUpdate;
  row: Record<string, any>;
  column_names: Array<string | Array<string>>;
}

interface PerspectiveSelectEventDetail {
  view_window: ViewWindow;
}