Core Viewer Element

// Register the custom element (side effect of import)
import "@finos/perspective-viewer";

// Static method for plugin registration
PerspectiveViewerElement.registerPlugin(name: string): Promise<void>;

import "@finos/perspective-viewer";

// Element is now available for use
const viewer = document.createElement("perspective-viewer");

/**
 * Loads a Table (or Promise returning a Table) into the viewer
 * Resolves when first frame of UI + visualization is drawn
 */
load(table: Promise<Table> | Table): Promise<void>;

/**
 * Gets the underlying Table for this viewer
 * @param wait_for_table - whether to wait for load() or fail immediately if no table loaded
 */
getTable(wait_for_table?: boolean): Promise<Table>;

/**
 * Gets the underlying View as currently configured by the user
 * Returns View owned by PerspectiveViewerElement (may be invalidated)
 */
getView(): Promise<View>;

/**
 * Gets edit port for the currently loaded Table
 * Throws if no Table loaded
 */
getEditPort(): number;

/**
 * Clears any error state and attempts to restore functionality
 */
resetError(): Promise<void>;

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

const viewer = document.createElement("perspective-viewer");

// Load data from various sources
const table = await perspective.table([
  { name: "Alice", age: 25 },
  { name: "Bob", age: 30 }
]);
await viewer.load(table);

// Access the underlying table and view
const loadedTable = await viewer.getTable();
const currentView = await viewer.getView();

/**
 * Saves element to serialized state object
 * @param format - Output format (default: "json")
 */
save(format?: "json" | "string" | "arraybuffer"): Promise<ViewerConfig>;

/**
 * Restores element from full/partial ViewerConfig
 * Accepts config from save() in any supported format
 */
restore(config: ViewerConfig): Promise<void>;

/**
 * Resets viewer's ViewerConfig to default
 * @param reset_all - if true, clears expressions and column settings too
 */
reset(reset_all?: boolean): Promise<void>;

/**
 * Clears any error state and attempts to restore functionality
 */
resetError(): Promise<void>;

// Save current configuration
const config = await viewer.save();

// Restore specific configuration
await viewer.restore({
  plugin: "d3_y_bar",
  group_by: ["category"],
  columns: ["sales"],
  theme: "Pro Dark"
});

// Reset to defaults
await viewer.reset();

/**
 * Flushes any pending modifications
 * Resolves when all pending actions have been rendered
 */
flush(): Promise<void>;

/**
 * Recalculates dimensions and redraws
 * @param force - if false and auto-size enabled, disables auto-size with warning
 */
resize(force?: boolean): Promise<void>;

/**
 * Restyles all plugins from current document
 * Must be called for many runtime CSS changes to take effect
 */
restyleElement(): Promise<void>;

/**
 * Gets render statistics (some fields reset after each call)
 */
getRenderStats(): RenderStats;

/**
 * Enables/disables auto-size behavior with ResizeObserver
 * Default: enabled
 */
setAutoSize(autosize: boolean): void;

/**
 * Enables/disables auto-pause behavior with IntersectionObserver  
 * Default: enabled
 */
setAutoPause(autopause: boolean): void;

/**
 * Sets render throttling in milliseconds
 * null/undefined: adaptive throttling
 */
setThrottle(throttle?: number): void;

// Ensure all changes are rendered
await viewer.flush();

// Manually trigger resize
await viewer.resize();

// Update styles after CSS changes
await viewer.restyleElement();

// Check performance metrics
const stats = viewer.getRenderStats();
console.log(`FPS: ${stats.virtual_fps}`);

/**
 * Sets available theme names in status bar UI
 * May cause current theme to switch if not in new set
 */
resetThemes(themes?: string[]): Promise<void>;

/**
 * Toggles config panel open/closed
 * @param force - true=open, false=close, undefined=toggle
 */
toggleConfig(force?: boolean): Promise<void>;

// Set available themes
await viewer.resetThemes(["Pro Light", "Pro Dark", "Monokai"]);

// Toggle settings panel
await viewer.toggleConfig();

// Configure auto-sizing (now documented in Rendering & Display Control)
viewer.setAutoSize(true);
viewer.setThrottle(16); // 60 FPS

/**
 * Gets array of all registered plugin custom elements
 */
getAllPlugins(): HTMLElement[];

/**
 * Gets plugin Custom Element by name, or active plugin if no name provided
 */
getPlugin(name?: string): PerspectiveViewerPlugin;

// Get all available plugins
const plugins = viewer.getAllPlugins();
console.log(plugins.map(p => p.name));

// Get specific plugin
const barChart = viewer.getPlugin("d3_y_bar");

// Get currently active plugin
const activePlugin = viewer.getPlugin();

/**
 * Returns currently selected region as ViewWindow
 */
getSelection(): ViewWindow | null;

/**
 * Sets selection ViewWindow for this element
 * Dispatches "perspective-select" event if selection changes
 */
setSelection(window?: ViewWindow): void;

/**
 * Toggles column settings sidebar for specific column
 * Dispatches "perspective-toggle-column-settings" event
 */
toggleColumnSettings(column_name: string): Promise<void>;

/**
 * Opens/closes column settings for specific column (null to close)
 * @param toggle - whether to toggle if already open
 */
openColumnSettings(column_name?: string, toggle?: boolean): Promise<void>;

// Get current selection
const selection = viewer.getSelection();
if (selection) {
  console.log(`Selected rows ${selection.start_row}-${selection.end_row}`);
}

// Set selection programmatically
viewer.setSelection({
  start_row: 0,
  end_row: 10,
  start_col: 0,
  end_col: 2
});

// Open column settings
await viewer.openColumnSettings("sales");

/**
 * Downloads View data as CSV file
 * @param flat - whether to use current ViewConfig or default
 */
download(flat?: boolean): Promise<void>;

/**
 * Copies View/Table data to system clipboard
 * @param method - Export format (default: CSV)
 */
copy(method?: ExportMethod): Promise<void>;

// Download current view as CSV
await viewer.download();

// Copy to clipboard
await viewer.copy("Csv");

/**
 * Deletes internal View and frees all resources
 * Makes viewer unusable - calling any method after will throw
 * Must be called to prevent WASM memory leaks
 */
delete(): Promise<void>;

/**
 * Restarts viewer to initial state before load()
 * Use if planning to call load() again (vs delete() if finished)
 */
eject(): Promise<void>;

// Clean restart for new data
await viewer.eject();
await viewer.load(newTable);

// Complete cleanup (when done with viewer)
await viewer.delete();

interface ViewerConfig {
  version?: string;
  plugin?: string;
  title?: string;
  theme?: string;
  settings?: boolean;
  plugin_config?: any;
  columns_config?: Record<string, ColumnConfigValues>;
  // Includes all ViewConfig properties...
}

interface RenderStats {
  virtual_fps: number;
  actual_fps: number;
  view_time: number;
  draw_time: number;
  render_time: number;
  total_time: number;
  num_columns: number;
  num_rows: number;
  is_pivot: boolean;
}

type ExportMethod = "Csv" | "Json" | "Html" | "Png" | "Excel" | "Arrow";