Perspective Workspace is a TypeScript library that provides a sophisticated workspace component for coordinating multiple <perspective-viewer> instances. Built on Lumino.js, it offers advanced UI management features including drag-and-drop docking, tabbed interfaces, global filtering, and complete state serialization for building interactive analytics dashboards.
npm install @finos/perspective-workspaceimport { HTMLPerspectiveWorkspaceElement } from "@finos/perspective-workspace";For additional components:
import {
PerspectiveWorkspace,
PerspectiveViewerWidget
} from "@finos/perspective-workspace";import { HTMLPerspectiveWorkspaceElement } from "@finos/perspective-workspace";
// Create workspace element
const workspace = document.createElement("perspective-workspace") as HTMLPerspectiveWorkspaceElement;
document.body.appendChild(workspace);
// Add a table
import * as perspective from "@finos/perspective";
const table = await perspective.table([
{ name: "Alice", age: 25, city: "New York" },
{ name: "Bob", age: 30, city: "London" }
]);
await workspace.addTable("users", Promise.resolve(table));
// Add a viewer
await workspace.addViewer({
table: "users",
columns: ["name", "age"],
group_by: ["city"]
});
// Save and restore workspace state
const config = workspace.save();
// Later...
workspace.restore(config);Perspective Workspace is built around several key components:
HTMLPerspectiveWorkspaceElement provides a simple HTML-based APIPerspectiveWorkspace class handles layout management and coordinationPerspectiveViewerWidget wraps individual perspective-viewer instancesCore workspace functionality for managing multiple perspective-viewer instances with docking, tabbing, and layout coordination.
class HTMLPerspectiveWorkspaceElement extends HTMLElement {
/** Persists workspace to serializable token */
save(): PerspectiveWorkspaceConfig<string>;
/** Restores workspace from configuration */
restore(layout: PerspectiveWorkspaceConfig<string>): Promise<void>;
/** Clears workspace to empty state */
clear(): Promise<void>;
/** Awaits all async tasks for all viewers */
flush(): Promise<void>;
/** Invalidates dimensions and recalculates layout */
resize(): Promise<void>;
/** Sets auto-sizing behavior for responsive layouts */
setAutoSize(is_auto_size: boolean): void;
}Table sharing and coordination system for managing perspective Tables across multiple viewers.
interface HTMLPerspectiveWorkspaceElement {
/** Adds table by name for sharing across viewers */
addTable(name: string, table: Promise<psp.Table>): Promise<void>;
/** Retrieves table by name */
getTable(name: string): psp.Table | Promise<psp.Table>;
/** Replaces existing table with new one */
replaceTable(name: string, table: Promise<psp.Table>): Promise<void>;
/** Removes table by name from workspace */
removeTable(name: string): boolean;
/** Map of perspective Tables by name */
readonly tables: ObservableMap<string, psp.Table | Promise<psp.Table>>;
}System for adding, configuring, and managing individual perspective-viewer instances within the workspace.
interface HTMLPerspectiveWorkspaceElement {
/** Adds new viewer to workspace with configuration */
addViewer(config: ViewerConfigUpdateExt): Promise<void>;
/** Awaits all async tasks for all viewers */
flush(): Promise<void>;
}
interface ViewerConfigUpdateExt extends ViewerConfigUpdate {
table: string;
}Layout management capabilities including auto-sizing, manual resizing, and responsive behavior.
interface HTMLPerspectiveWorkspaceElement {
/** Invalidates dimensions and recalculates layout */
resize(): Promise<void>;
/** Sets auto-sizing behavior for responsive layouts */
setAutoSize(is_auto_size: boolean): void;
}interface PerspectiveWorkspaceConfig<T> {
sizes: number[];
master: PerspectiveLayout<T>;
detail: PerspectiveLayout<T>;
viewers: Record<string, ViewerConfigUpdateExt>;
}
interface PerspectiveLayout<T> {
children?: PerspectiveLayout<T>[];
widgets?: T[];
sizes: number[];
}
interface ViewerConfigUpdateExt extends ViewerConfigUpdate {
table: string;
}