tessl/npm-finos--perspective-viewer

The `<perspective-viewer>` Custom Element, frontend for Perspective.js, providing interactive analytics and data visualization.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Perspective Viewer

Name: tessl/npm-finos--perspective-viewer
Author: tessl

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;
}