or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

chart-elements.md chart-types.md index.md plugin-registration.md

tile.json

Plugin Registration

The plugin registration system is responsible for defining custom HTML elements for each chart type and registering them with the Perspective viewer system.

Capabilities

Register Function

Registers chart plugins as custom HTML elements in the browser's custom element registry and with the Perspective viewer plugin system.

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

Usage Examples:

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

// Register all available chart plugins
register();

// Register specific chart plugins only
register("Y Area", "Y Line", "Heatmap");

// Register a single chart plugin
register("Y Area");

Behavior:

Creates custom HTML elements for each specified chart type
Element names follow the pattern: perspective-viewer-d3fc-{chart-name}
Each element extends HTMLPerspectiveViewerD3FCPluginElement
Automatically registers with the perspective-viewer once it's available
Idempotent - safe to call multiple times

Available Chart Plugin Names

The following chart plugin names can be used with the register() function:

type ChartPluginName = 
  | "Y Area"
  | "X Bar" 
  | "Candlestick"
  | "Y Bar"
  | "Heatmap"
  | "Y Line"
  | "OHLC"
  | "Sunburst"
  | "Treemap"
  | "X/Y Line"
  | "X/Y Scatter"
  | "Y Scatter";

Chart Plugin Metadata

Each chart implementation includes plugin metadata that defines its capabilities and constraints:

interface ChartPluginMetadata {
  /** Display name of the chart plugin */
  name: string;
  /** Category for grouping in UI */
  category: string;
  /** Maximum number of data cells the chart can render efficiently */
  max_cells: number;
  /** Maximum number of columns the chart can handle */
  max_columns: number;
  /** Whether to show performance warnings for large datasets */
  render_warning: boolean;
  /** Initial configuration requirements */
  initial: {
    /** Expected data type for initial setup */
    type?: string;
    /** Minimum number of columns required */
    count?: number;
    /** Default column names or labels */
    names: string[];
  };
  /** Selection interaction mode */
  selectMode?: string;
}

Custom Element Creation

The registration process creates custom HTML elements with the following naming convention:

// Element names created by register()
type ElementName =
  | "perspective-viewer-d3fc-area"      // Y Area
  | "perspective-viewer-d3fc-xbar"      // X Bar  
  | "perspective-viewer-d3fc-candlestick" // Candlestick
  | "perspective-viewer-d3fc-ybar"      // Y Bar
  | "perspective-viewer-d3fc-heatmap"   // Heatmap
  | "perspective-viewer-d3fc-yline"     // Y Line
  | "perspective-viewer-d3fc-ohlc"      // OHLC
  | "perspective-viewer-d3fc-sunburst"  // Sunburst
  | "perspective-viewer-d3fc-treemap"   // Treemap
  | "perspective-viewer-d3fc-xyline"    // X/Y Line
  | "perspective-viewer-d3fc-xyscatter" // X/Y Scatter
  | "perspective-viewer-d3fc-yscatter"  // Y Scatter

Element Name Generation:

Converts plugin name to lowercase
Removes spaces, tabs, returns, and forward slashes
Prefixes with perspective-viewer-d3fc-

Integration with Perspective Viewer

/**
 * Registers a plugin element with the perspective-viewer system
 * @param plugin_name - The custom element name to register
 */
async function register_element(plugin_name: string): Promise<void>;

This function is called automatically during the registration process to ensure each chart plugin is available for use within perspective-viewer components.

Default Plugin Settings

interface DefaultPluginSettings {
  initial: {
    type: string;
    count: number;
    names: string[];
  };
  selectMode: string;
}

const DEFAULT_PLUGIN_SETTINGS: DefaultPluginSettings = {
  initial: {
    type: "number",
    count: 1,
    names: [],
  },
  selectMode: "select",
};

These defaults are used when chart implementations don't specify their own initial configuration.

CSS and Styling Integration

The registration process also handles CSS integration for D3FC components:

// CSS stylesheets applied to all chart elements
const D3FC_GLOBAL_STYLES: CSSStyleSheet[];

This includes:

D3FC chart component styles
D3FC element styles
Custom perspective-viewer-d3fc styles

The stylesheets are automatically applied to each chart element's shadow DOM during the connectedCallback lifecycle method.

Version

Tile

Files