@perspective-dev/viewer-charts 4.3.0

package/dist/esm/plugin/charts.d.ts

@@ -0,0 +1,40 @@
+import type { PluginConfig } from "../charts/chart";
+export type ChartType = "bar" | "line" | "scatter" | "area";
+export type PluginChartType = ChartType | "candlestick" | "ohlc";
+/**
+ * Subset of `PluginConfig` keys that a chart impl actually consumes.
+ * Drives `plugin_config_schema()` filtering — the host only renders
+ * the controls listed here, and `plugin.restore({ plugin_config })`
+ * still hands the full struct to the worker (other keys are inert).
+ */
+export type PluginConfigField = keyof PluginConfig;
+export interface ChartTypeConfig {
+    name: string;
+    tag: string;
+    category: string;
+    selectMode: "select" | "toggle";
+    initial: {
+        count: number;
+        names: string[];
+    };
+    max_cells: number;
+    max_columns: number;
+    default_chart_type?: PluginChartType;
+    /**
+     * Plugin-config keys this chart type renders controls for. Empty
+     * for plugins with no global settings (heatmap / treemap /
+     * sunburst). See {@link PluginConfig} for field semantics.
+     */
+    applicable_plugin_fields: readonly PluginConfigField[];
+    /**
+     * Per-chart-type overrides for `DEFAULT_PLUGIN_CONFIG`. Used when a
+     * field's sensible default differs by chart family — currently
+     * `include_zero` (true for Y Bar / Y Area / X Bar, false for line
+     * / scatter / cartesian / financial). Applied at schema generation
+     * and at `restore({})` so the effective default matches the
+     * surfaced UI default.
+     */
+    plugin_field_defaults?: Partial<PluginConfig>;
+}
+declare const CHARTS: ChartTypeConfig[];
+export default CHARTS;

package/dist/esm/plugin/plugin.d.ts

@@ -0,0 +1,95 @@
+import type { View } from "@perspective-dev/client";
+import type { IPerspectiveViewerPlugin, PluginStaticConfig } from "@perspective-dev/viewer";
+import { ChartTypeConfig } from "./charts";
+export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement implements IPerspectiveViewerPlugin {
+    _chartType: ChartTypeConfig;
+    private _initialized;
+    private _glCanvas;
+    private _gridlineCanvas;
+    private _chromeCanvas;
+    private _renderer;
+    private _rendererPromise;
+    private _rawEventForwarder;
+    private _generation;
+    private _renderBlitMode;
+    private _resetClickAbort;
+    /**
+     * Plugin-scoped global config. Seeded lazily from
+     * `_effectiveDefaults()` (which folds
+     * `_chartType.plugin_field_defaults` over `DEFAULT_PLUGIN_CONFIG`)
+     * because base-class field initializers run before the subclass
+     * `_chartType` assignment. `restore({ plugin_config })` merges
+     * incoming values on top of the same effective defaults so fields
+     * the host omits fall back to the chart-type default
+     * (`include_zero = true` for Y Bar / Y Area / X Bar, `false`
+     * elsewhere). Held on the element (not just inside the worker) so
+     * a `_buildRenderer` triggered after a `restore` ships the
+     * resolved values in the `InitMsg`.
+     */
+    private _pluginConfigStore;
+    private get _pluginConfig();
+    private set _pluginConfig(value);
+    private _effectiveDefaults;
+    connectedCallback(): void;
+    private _buildCanvasStack;
+    private _clearCanvasStack;
+    /**
+     * Fires when the host (`<perspective-viewer>`) removes this plugin
+     * from the DOM on chart-type switch — see
+     * `renderer/activate.rs::remove_inactive_plugin`. Without this,
+     * inactive plugin instances retain their `RendererTransport`
+     * (worker + WebGL context + compiled shader programs) until the
+     * entire viewer is torn down, so a user cycling all 12 chart kinds
+     * holds 12 GL contexts per viewer and routinely exceeds the
+     * browser's per-page context cap (~16) in workspaces.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Lazy renderer construction. Memoizes the in-flight `init()`
+     * promise so concurrent `draw()` calls during async setup await
+     * the same initialization rather than racing.
+     */
+    private _ensureRenderer;
+    /**
+     * Capture raw DOM events on the GL canvas with `RawEventForwarder`
+     * and post them over the control channel. The renderer dispatches
+     * them through its own resolver + `applyWheel` / `applyPan` for
+     * zoom/pan, and through `TooltipController` virtual dispatch for
+     * hover/click; `zoomChanged` updates push back so the reset-zoom
+     * button visibility tracks the renderer-side state.
+     *
+     * The `zoomChanged` callback was wired at `RendererTransport`
+     * construction time; here we just attach the event forwarder and
+     * the reset-button click handler.
+     */
+    private _setupInteraction;
+    private _buildRenderer;
+    setBlitMode(mode: "direct" | "blit"): void;
+    get_static_config(): PluginStaticConfig;
+    column_config_schema(column_type: string, _group: string | undefined, _column_name: string, current_value: Record<string, unknown> | null, _viewer_config?: {
+        group_by?: string[];
+        group_rollup_mode?: string;
+    }): {
+        fields: (Record<string, unknown> & {
+            kind: string;
+        })[];
+    };
+    plugin_config_schema(_view_config?: {
+        group_by?: string[];
+        group_rollup_mode?: string;
+    }): {
+        fields: (Record<string, unknown> & {
+            kind: string;
+        })[];
+    };
+    draw(view: View): Promise<void>;
+    update(view: View): Promise<void>;
+    private _drawImpl;
+    clear(): Promise<void>;
+    resize(): Promise<void>;
+    restyle(): number;
+    save(): any;
+    render(view: View): Promise<Blob>;
+    restore(config: any, columns_config?: Record<string, any>): void;
+    delete(): void;
+}

package/dist/esm/render/scheduler.d.ts

@@ -0,0 +1,41 @@
+import type { WebGLContextManager } from "../webgl/context-manager";
+/**
+ * Request a coalesced render of `glManager` whose body is
+ * `fullRender`. Returns a promise that resolves when this entry's
+ * Phase 2 (`awaitGpuFence` + `endFrame`) completes.
+ *
+ * If a request is already pending for the same glManager, the new
+ * call's `fullRender` closure replaces the prior one (latest call
+ * wins; closures read chart state lazily so this is functionally a
+ * no-op, but keeps the closure fresh) and the returned promise
+ * resolves alongside the existing waiters.
+ */
+export declare function requestRender(glManager: WebGLContextManager, fullRender: () => void): Promise<void>;
+/**
+ * Run `op` synchronously if no drain `present()` is currently active
+ * for `glManager`. Otherwise queue `op` to run as soon as that
+ * glManager's in-flight `present()` completes (after `endFrame`,
+ * after the resolved/rejected waiters).
+ *
+ * Used by canvas-mutating callers — `WorkerRenderer.resize`,
+ * `WorkerRenderer.clear` — to avoid wiping the offscreen between
+ * Phase 1 paint and Phase 2 `endFrame`. `glManager.resize` setting
+ * `canvas.width = N` clears the drawing buffer immediately
+ * (per the WebGL spec, out-of-band from the GL command queue), and
+ * a clear that lands in Phase 2's fence-wait yield window corrupts
+ * the bitmap that `transferToImageBitmap` ships, producing a blank
+ * frame on the host.
+ *
+ * Deferred ops execute in `present()`'s `finally` clause, so they
+ * land *after* the in-flight drain's bitmap has been shipped and
+ * before the next drain starts. If a deferred op itself triggers a
+ * `requestRender`, the resulting entry queues into `pending` and
+ * the drain's tail check (`pending.size > 0 → scheduleFrame(drain)`)
+ * picks it up for the next RAF.
+ */
+export declare function deferIfDraining(glManager: WebGLContextManager, op: () => void): void;
+/**
+ * Test-only: clear pending state. Production callers must not use
+ * this — outstanding waiters are silently dropped.
+ */
+export declare function _resetForTest(): void;

package/dist/esm/theme/gradient.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A single stop on a parsed CSS gradient. `offset` ∈ [0, 1].
+ */
+export interface GradientStop {
+    offset: number;
+    color: [number, number, number, number];
+}
+/**
+ * Parse a `linear-gradient(...)` CSS expression into ordered stops. Tolerates
+ * missing percentages (distributes linearly between known offsets, matching
+ * the CSS standard) and leading direction tokens (`to right`, `90deg`, etc.)
+ * which are simply skipped.
+ *
+ * Returns the default blue → orange two-stop on any parse failure so themes
+ * that never set the gradient still produce sane output.
+ */
+export declare function parseCssGradient(src: string | null | undefined): GradientStop[];
+/**
+ * Piecewise-linear color sample at `t ∈ [0, 1]`. Returns RGBA in [0, 1].
+ * Clamps `t` to the gradient's first/last stop outside `[0, 1]`.
+ */
+export declare function sampleGradient(stops: GradientStop[], t: number): [number, number, number, number];
+/**
+ * Sign-aware normalization. Returns `t ∈ [0, 1]` where the 50% stop is
+ * always the sign pivot:
+ *   - crosses zero → `[-maxAbs, maxAbs]` stretched symmetrically; 0 → 0.5.
+ *   - all-positive → `[0, colorMax]` occupies top half `[0.5, 1]`.
+ *   - all-negative → `[colorMin, 0]` occupies bottom half `[0, 0.5]`.
+ *   - degenerate   → 0.5 (single colour at the midpoint).
+ */
+export declare function colorValueToT(value: number, colorMin: number, colorMax: number): number;
+/**
+ * Convert a discrete series palette (from `--psp-charts--series-N--color`)
+ * into a `GradientStop[]` with stops at `i / (N - 1)`. The resulting
+ * stops can feed `buildGradientLUT` / `ensureGradientTexture` / any
+ * other code path that already accepts a gradient — so categorical
+ * coloring and numeric gradients share one LUT pipeline. Integer idx
+ * sampling via `t = idx / (N - 1)` lands exactly on a palette color;
+ * the linear blend between stops is only hit by non-integer samples
+ * (which categorical data doesn't produce).
+ */
+export declare function paletteToStops(palette: [number, number, number][]): GradientStop[];
+/**
+ * Bake a sampled LUT for GPU upload as RGBA8 (`size × 1`). Default 256
+ * samples — visually indistinguishable from a denser sample at typical
+ * viewport sizes and keeps the texture tiny (1 KB).
+ */
+export declare function buildGradientLUT(stops: GradientStop[], size?: number): Uint8Array;

package/dist/esm/theme/palette.d.ts

@@ -0,0 +1,13 @@
+import { type GradientStop } from "./gradient";
+export type Vec3 = [number, number, number];
+/**
+ * Build a series palette of length `count` by sampling the theme gradient
+ * at evenly-spaced offsets. For count == 1 returns the 50% stop.
+ */
+export declare function interpolatePalette(stops: GradientStop[], count: number): Vec3[];
+/**
+ * Resolve a series palette: use the discrete `--psp-charts--series-N--color`
+ * palette when available, otherwise fall back to evenly-spaced samples of
+ * the theme gradient.
+ */
+export declare function resolvePalette(discrete: Vec3[], stops: GradientStop[], count: number): Vec3[];

package/dist/esm/theme/theme-snapshot.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeSnapshot } from "./theme";
+/**
+ * Capture every CSS variable the renderer cares about into a
+ * structured-cloneable map. Series-palette colours are walked until the
+ * first missing var.
+ */
+export declare function snapshotThemeVars(el: Element): ThemeSnapshot;

package/dist/esm/theme/theme.d.ts

@@ -0,0 +1,53 @@
+import { type GradientStop } from "./gradient";
+export type { GradientStop } from "./gradient";
+export interface Theme {
+    fontFamily: string;
+    tickColor: string;
+    labelColor: string;
+    axisLineColor: string;
+    gridlineColor: string;
+    backgroundColor: string;
+    gradientStops: GradientStop[];
+    legendText: string;
+    legendBorder: string;
+    tooltipBg: string;
+    tooltipText: string;
+    tooltipBorder: string;
+    /**
+     * Fill opacity for area glyphs. `--psp-charts--area--opacity`.
+     */
+    areaOpacity: number;
+    /**
+     * Pixel gap between heatmap cells. Controls the inset applied in the
+     * heatmap vertex shader so neighbouring cells remain visually
+     * distinguishable. `--psp-charts--heatmap-gap--px`.
+     */
+    heatmapGapPx: number;
+    /**
+     * Pixel gap between sunburst arcs (both radial — between ring
+     * levels — and angular — between siblings). Works the same way as
+     * `heatmapGapPx`: a symmetric inset in the vertex shader so the
+     * transparent background shows through as a border.
+     * `--psp-charts--sunburst-gap--px`.
+     */
+    sunburstGapPx: number;
+    /**
+     * Discrete series palette read from `--psp-charts--series-N--color`
+     * (N = 1, 2, …). Empty when no palette is defined — callers should
+     * fall back to `gradientStops` sampling in that case.
+     */
+    seriesPalette: [number, number, number][];
+}
+/**
+ * Plain map of CSS variable name → resolved value. Produced on the
+ * main thread via `snapshotThemeVars` and shipped to the worker
+ * Renderer (which has no DOM and can't call `getComputedStyle`).
+ */
+export type ThemeSnapshot = Record<string, string>;
+/**
+ * Decode a `ThemeSnapshot` into the parsed `Theme` the renderer
+ * consumes. Workers reach this from a serialized snapshot; host code
+ * snapshots from the live DOM via `theme-snapshot.ts` and feeds it
+ * through here.
+ */
+export declare function resolveThemeFromVars(vars: ThemeSnapshot): Theme;