or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

chart-elements.mdchart-types.mdindex.mdplugin-registration.md
tile.json

index.mddocs/

Perspective Viewer D3FC

Perspective Viewer D3FC is a comprehensive D3FC-based visualization plugin for the Perspective.js analytics platform. It provides 12 distinct chart types including area charts, bar charts, candlestick charts, column charts, heatmaps, line charts, OHLC charts, sunburst charts, treemap charts, and scatter plots. Built with TypeScript, it leverages D3FC's modular charting components and D3.js selection/data binding APIs to create interactive, high-performance data visualizations that integrate seamlessly with Perspective's streaming query engine.

Package Information

  • Package Name: @finos/perspective-viewer-d3fc
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @finos/perspective-viewer-d3fc
  • Version: 3.8.0
  • License: Apache-2.0

Core Imports

Main import (registers all chart plugins):

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

Individual chart imports:

import "@finos/perspective-viewer-d3fc/area";
import "@finos/perspective-viewer-d3fc/bar";
import "@finos/perspective-viewer-d3fc/candlestick";
import "@finos/perspective-viewer-d3fc/column";
import "@finos/perspective-viewer-d3fc/heatmap";
import "@finos/perspective-viewer-d3fc/line";
import "@finos/perspective-viewer-d3fc/ohlc";
import "@finos/perspective-viewer-d3fc/sunburst";
import "@finos/perspective-viewer-d3fc/xy-scatter";
import "@finos/perspective-viewer-d3fc/y-scatter";

Note: The XY Line chart ("X/Y Line" plugin) and Treemap chart ("Treemap" plugin) are available when importing the main package but do not have dedicated individual import paths in the package.json exports.

Plugin registration function:

import { register } from "@finos/perspective-viewer-d3fc/src/plugin/plugin";

Basic Usage

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

// Create a Perspective table
const table = await perspective.table({
  symbol: ["AAPL", "GOOGL", "MSFT", "AAPL", "GOOGL", "MSFT"],
  price: [150.5, 2800.0, 300.2, 151.2, 2795.5, 301.1],
  timestamp: [new Date(), new Date(), new Date(), new Date(), new Date(), new Date()]
});

// Create and configure perspective-viewer with D3FC plugin
const viewer = document.createElement("perspective-viewer");
viewer.load(table);

// Configure to use a D3FC chart
await viewer.restore({
  plugin: "perspective-viewer-d3fc-yline",
  columns: ["price"],
  group_by: ["symbol"],
  split_by: [],
  aggregates: {},
  filter: []
});

document.body.appendChild(viewer);

Architecture

Perspective Viewer D3FC is built around several key architectural components:

  • Plugin System: Uses Perspective's plugin architecture to register chart types as custom HTML elements
  • Web Components: Each chart type is implemented as a custom HTML element extending HTMLPerspectiveViewerD3FCPluginElement
  • D3FC Integration: Leverages D3FC's modular charting components for rendering SVG and Canvas visualizations
  • Chart Factory: Centralizes axis configuration and chart composition logic
  • Data Processing: Transforms Perspective view data into formats suitable for D3FC charts
  • Styling System: Integrates with Perspective's theming system and provides D3FC-specific styling

Global Type Definitions

declare global {
  interface CustomElementRegistry {
    get(tagName: "perspective-viewer-d3fc-area"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-xbar"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-candlestick"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-ybar"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-heatmap"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-yline"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-ohlc"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-sunburst"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-treemap"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-xyline"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-xyscatter"): typeof HTMLPerspectiveViewerD3FCPluginElement;
    get(tagName: "perspective-viewer-d3fc-yscatter"): typeof HTMLPerspectiveViewerD3FCPluginElement;

    whenDefined(tagName: "perspective-viewer-d3fc-area"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-xbar"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-candlestick"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-ybar"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-heatmap"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-yline"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-ohlc"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-sunburst"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-treemap"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-xyline"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-xyscatter"): Promise<void>;
    whenDefined(tagName: "perspective-viewer-d3fc-yscatter"): Promise<void>;
  }

  export interface HTMLPerspectiveViewerD3FCPluginElement extends IPerspectiveViewerPlugin {}

  export class HTMLPerspectiveViewerD3FCPluginElement extends HTMLElement implements IPerspectiveViewerPlugin {
    static get max_cells(): number;
    static set max_cells(value: number);
  }
}

Capabilities

Plugin Registration

Core functionality for registering chart plugins as custom HTML elements in the browser's custom element registry.

/**
 * Registers chart plugins as custom HTML elements
 * @param plugin_names - Optional list of plugin names to register (defaults to all available charts)
 */
function register(...plugin_names: string[]): void;

Plugin Registration

Chart Elements

Custom HTML elements that implement the Perspective plugin interface for different chart types. Each element is a web component that renders a specific type of D3FC-based visualization.

class HTMLPerspectiveViewerD3FCPluginElement extends HTMLElement implements IPerspectiveViewerPlugin {
  // Static configuration
  static get max_cells(): number;
  static set max_cells(value: number);
  static get max_columns(): number;
  static set max_columns(value: number);

  // Instance properties
  get name(): string;
  get category(): string;
  get select_mode(): string;
  get min_config_columns(): number;
  get config_column_names(): string[];
  get max_cells(): number;
  set max_cells(value: number);
  get max_columns(): number;
  set max_columns(value: number);

  // Lifecycle and rendering methods
  connectedCallback(): void;
  render(): Promise<Blob>;
  draw(view: any, end_col?: number, end_row?: number): Promise<void>;
  update(view: any, end_col?: number, end_row?: number, clear?: boolean): Promise<void>;
  clear(): Promise<void>;
  resize(view: any): Promise<void>;
  restyle(view: any, end_col?: number, end_row?: number): Promise<void>;
  delete(): Promise<void>;

  // Configuration methods
  getContainer(): HTMLElement;
  save(): Settings;
  restore(settings: Settings, columns_config: ColumnConfigValues): void;

  // Style capability methods
  can_render_column_styles(type: Type, group?: string): boolean;
  column_style_controls(type: Type, group?: string): unknown;
}

Chart Elements

Chart Types

Individual chart implementations providing different visualization types for various data patterns and use cases.

interface Chart {
  (container: HTMLSelection, settings: Settings): void;
  plugin?: {
    name: string;
    category: string;
    max_cells: number;
    max_columns: number;
    render_warning: boolean;
    initial: {
      type?: string;
      count?: number;
      names: string[];
    };
    selectMode?: string;
  };
  can_render_column_styles?(type: Type, group?: string): boolean;
  column_style_controls?(type: Type, group?: string): unknown;
}

Available chart types:

  • Y Area: Area chart with Y-axis values
  • X Bar: Horizontal bar chart
  • Candlestick: Financial candlestick chart for OHLC data
  • Y Bar: Vertical bar chart (column chart)
  • Heatmap: 2D heatmap visualization
  • Y Line: Line chart with Y-axis values
  • OHLC: Open/High/Low/Close financial chart
  • Sunburst: Hierarchical sunburst chart
  • Treemap: Hierarchical treemap visualization
  • X/Y Line: Line chart with both X and Y axes
  • X/Y Scatter: Scatter plot with both X and Y axes
  • Y Scatter: Scatter plot with Y-axis values

Chart Types

Core Types

type Type = "integer" | "string" | "boolean" | "date" | "datetime" | "float";

type HTMLSelection<E extends d3.BaseType = HTMLElement> = d3.Selection<
  E,
  unknown,
  undefined,
  unknown
>;

interface Settings {
  hideKeys?: any[];
  agg_paths?: any;
  axisMemo: Axis[];
  colorStyles?: ColorStyles;
  crossValues: any[];
  data: any[];
  filter: any[];
  mainValues: MainValue[];
  splitMainValues?: string[];
  realValues: string[];
  size: DOMRect;
  splitValues: any[];
  textStyles: TextStyles;
  sunburstLevel?: any;
  columns_config?: ColumnConfigValues;
  treemaps?: Record<string, TreemapValue>;
}

interface MainValue {
  name: string;
  type: any;
}

type ColorStyles = {
  scheme: string[];
  gradient?: Record<GradientKey, GradientPair[]>;
  interpolator: { [key: string]: (value: number) => string };
  grid: { gridLineColor?: string };
  opacity?: number;
  series?: string;
  [key: `series-${number}`]: string;
};

type TextStyles = Record<string, string>;

type Axis = [number, number];
type GradientPair = [number, string];
type GradientKey = string;