@perspective-dev/viewer-charts 4.3.0

package/dist/esm/charts/chart-base.d.ts

@@ -0,0 +1,402 @@
+import type { View } from "@perspective-dev/client";
+import type { ColumnDataMap } from "../data/view-reader";
+import { LazyRowFetcher } from "../data/lazy-row";
+import type { WebGLContextManager } from "../webgl/context-manager";
+import { ZoomController, type ZoomConfig } from "../interaction/zoom-controller";
+import { type ChartImplementation, type FacetConfig, type PluginConfig } from "./chart";
+import { TooltipController, type HostSink, type TooltipCallbacks } from "../interaction/tooltip-controller";
+import type { PerspectiveClickDetail } from "../event-detail";
+import type { ViewConfig } from "@perspective-dev/client";
+import { type Theme } from "../theme/theme";
+/**
+ * Base class for WebGL chart implementations. Owns the common lifecycle
+ * plumbing (canvas wiring, viewer config setters, tooltip controller)
+ * so each concrete chart only implements data pipeline, rendering, and
+ * destruction hooks.
+ *
+ * ## Frame lifecycle (three phases)
+ *
+ * Every render of a chart passes through three phases:
+ *
+ * 1. `uploadAndRender(glManager, columns, startRow, endRow)`.
+ *    Driven by the plugin wrapper once per data chunk. The subclass
+ *    runs its build pipeline (axis/series resolution, record
+ *    generation, domain accumulation) and pushes typed-array results
+ *    into GPU buffers via `glManager.bufferPool`. Most charts also
+ *    compile their shaders lazily here on first call.
+ *
+ * 2. `requestRender(glManager)` — single entrypoint for triggering a
+ *    paint. Routes through the module-level scheduler
+ *    ([render/scheduler.ts]) which coalesces by glManager and runs
+ *    `_fullRender` + `awaitGpuFence` + `endFrame` on the next RAF.
+ *    Concurrent requests collapse to one `_fullRender` per frame and
+ *    fence waits across charts run in parallel, so per-chart latency
+ *    is bounded by that chart's own GPU work.
+ *
+ * 3. `_fullRender(glManager)` — the subclass implements its own draw
+ *    loop: resolve visible domains from the zoom controller, build
+ *    projection matrices, call into its glyph draw helpers, and paint
+ *    the chrome overlay (axes, legend, tooltip).
+ *
+ * `destroy()` is called by the plugin wrapper on teardown. It detaches
+ * tooltip listeners, then invokes the subclass's `destroyInternal()`
+ * to free chart-specific GL resources.
+ *
+ * ## What subclasses implement
+ *   - `uploadAndRender` — phase 1; ends by `await this.requestRender(glManager)`.
+ *   - `tooltipCallbacks()` — return chart-specific hover/click handlers.
+ *   - `_fullRender` — phase 3; must be safe to call with no data
+ *     (subclass guards on its own state machine — empty trees, missing
+ *     programs, etc — and returns early without touching GL).
+ *   - `destroyInternal` — release chart-specific resources.
+ *
+ * `getZoomConfig()` is an optional override; default = both axes
+ * zoom-unlocked. See {@link ZoomConfig}.
+ */
+export declare abstract class AbstractChart implements ChartImplementation {
+    _glManager: WebGLContextManager | null;
+    _gridlineCanvas: HTMLCanvasElement | OffscreenCanvas | null;
+    _chromeCanvas: HTMLCanvasElement | OffscreenCanvas | null;
+    /**
+     * Host-supplied CSS-variable map. The host snapshots its DOM via
+     * `snapshotThemeVars(el)` and ships it over the control channel;
+     * the chart decodes via `resolveThemeFromVars` lazily in
+     * `_resolveTheme()`. The chart never reads the DOM itself (it
+     * always runs inside `WorkerRenderer`, possibly off-thread).
+     */
+    _themeVars: Record<string, string>;
+    _zoomController: ZoomController | null;
+    /**
+     * Per-facet zoom controllers. Populated when `zoom_mode ===
+     * "independent"` and the chart enters faceted mode; each facet's
+     * render path reads its own viewport from the matching entry.
+     *
+     * Shared-zoom mode leaves this empty; `_zoomController` is the
+     * single domain used for every facet.
+     */
+    _facetZoomControllers: ZoomController[];
+    _columnSlots: (string | null)[];
+    _groupBy: string[];
+    _splitBy: string[];
+    _columnTypes: Record<string, string>;
+    /**
+     * Effective shared-axis flags for the most recent faceted frame.
+     * Derived per-frame from `_facetConfig.shared_x_axis` /
+     * `shared_y_axis` and `zoom_mode` via
+     * {@link computeEffectiveFacetFlags} — independent-zoom mode forces
+     * both off because an outer axis band has no single domain it could
+     * display. Stored here (rather than mutated back onto
+     * `_facetConfig`) so the user's configured shared-axis preferences
+     * survive a "shared → independent → shared" round-trip. Read by
+     * chrome-overlay code (e.g. `renderFacetedChromeOverlay`,
+     * `renderFacetedHeatmapChromeOverlay`) after the main render pass
+     * sets them.
+     */
+    _lastEffectiveSharedX: boolean;
+    _lastEffectiveSharedY: boolean;
+    /**
+     * Source-column types for `group_by` columns — sourced from
+     * `table.schema()` (plain columns) merged with `view.expression_schema()`
+     * (expression-typed group_bys). Distinct from `_columnTypes` (which
+     * is the post-aggregation `view.schema()` map): the level-type
+     * lookup for `__ROW_PATH_N__` columns must use the unaggregated
+     * type, since `view.schema()` doesn't key these synthetic columns.
+     */
+    _groupByTypes: Record<string, string>;
+    _columnsConfig: Record<string, any>;
+    /**
+     * Pre-compiled per-column value formatters, keyed by the **source**
+     * column name (synthetic split-by paths are normalized via
+     * `sourceColumn`). Rebuilt by `setColumnsConfig` from the active
+     * plugin's `column_config_schema` output, then consulted by axis /
+     * tooltip / legend paths via {@link getColumnFormatter}.
+     *
+     * `undefined` means "no configured formatter for this column" — the
+     * caller falls back to the chart's hand-rolled tick formatter.
+     */
+    _columnFormatters: Map<string, (v: number) => string>;
+    _defaultChartType: string | undefined;
+    _facetConfig: FacetConfig;
+    /**
+     * Plugin-scoped global configuration. Updated by `setPluginConfig`
+     * (driven from the host's `plugin.restore()`) and read by render-
+     * path glyphs (`line_width_px`, `point_size_px`, etc.) and by the
+     * build pipelines (`auto_alt_y_axis`, `band_inner_frac`,
+     * `bar_inner_pad`). Defaults preserve the previous compile-time
+     * constants so first-frame rendering before `restore()` matches
+     * the pre-refactor output.
+     */
+    _pluginConfig: PluginConfig;
+    _tooltip: TooltipController;
+    /**
+     * Reference to the active host sink, captured in {@link attachTooltip}.
+     * Used to emit `perspective-click` / `perspective-global-filter` user
+     * events back to the host. Distinct from `_tooltip._host` to avoid
+     * reaching into the tooltip controller's internals.
+     */
+    _hostSink: HostSink | null;
+    /**
+     * Promise chain that serializes user-event emissions so a rapid
+     * pin → unpin sequence stays in order even when `buildClickDetail`
+     * awaits `_lazyRows.fetchRow`. Without the queue, click 1's async
+     * row fetch could resolve AFTER click 2's synchronous `emitUnselect`
+     * — flipping the host's observed event order. All emit helpers
+     * (`emitClickAndSelect`, `emitUserClick`, `emitUserSelect`,
+     * `emitUnselect`) chain through this.
+     */
+    _emitQueue: Promise<void>;
+    /**
+     * Cached resolved theme — populated on first `_resolveTheme()` call,
+     * cleared by `invalidateTheme()` (driven from `plugin.restyle()`).
+     * `getComputedStyle` / `getPropertyValue` reads cost ~100µs each;
+     * zoom/hover dispatch redraws at 60Hz so we resolve once and reuse.
+     */
+    _theme: Theme | null;
+    /**
+     * On-demand single-row fetcher used by lazy tooltip column
+     * lookups. Reset on every `setView` call; subclasses read
+     * `_lazyRows.fetchRow(rowIdx)` from their hover/pin paths and
+     * compare a captured serial against the current hovered/pinned
+     * state at resolution time, so stale fetches never paint.
+     *
+     * Can be `null` on chart types that don't surface the View
+     * (unit-tested charts) or before the first `draw`.
+     */
+    _lazyRows: LazyRowFetcher | null;
+    setGridlineCanvas(canvas: HTMLCanvasElement | OffscreenCanvas): void;
+    setChromeCanvas(canvas: HTMLCanvasElement | OffscreenCanvas): void;
+    setTheme(vars: Record<string, string>): void;
+    setZoomController(zc: ZoomController): void;
+    /**
+     * Resolve the zoom controller that owns facet `idx`. In shared-zoom
+     * mode (default) this is always the chart's single `_zoomController`.
+     * In independent-zoom mode the router provisions one controller per
+     * facet; this returns the matching entry, allocating on demand so
+     * the render path never has to check `zoom_mode` itself.
+     */
+    getZoomControllerForFacet(idx: number): ZoomController | null;
+    /**
+     * Derive the effective shared-X / shared-Y flags for the current
+     * frame and stamp them onto `_lastEffectiveSharedX/Y` for downstream
+     * chrome-overlay code to consume. Independent-zoom mode forces both
+     * shared flags off — the outer axis band cannot display per-cell
+     * viewports — without mutating the user's stored `_facetConfig`.
+     *
+     * Returns `{ independentZoom, effectiveSharedX, effectiveSharedY }`
+     * for callers that need the values immediately (e.g. to pass
+     * `xAxis: "outer" | "cell"` into `buildFacetGrid`).
+     */
+    computeEffectiveFacetFlags(): {
+        independentZoom: boolean;
+        effectiveSharedX: boolean;
+        effectiveSharedY: boolean;
+    };
+    /**
+     * Wire every active zoom controller's layout pointer for the
+     * supplied facet cells. In shared-zoom mode every
+     * `getZoomControllerForFacet(i)` returns the same `_zoomController`,
+     * so iterating past the first cell would just re-write the same
+     * pointer — `break`-on-shared keeps the cost O(1) and avoids the
+     * subtle bug where every facet's `updateLayout` overwrites the
+     * previous one with the last cell's layout.
+     */
+    syncFacetZoomLayouts(cells: ReadonlyArray<{
+        layout: import("../layout/plot-layout").PlotLayout;
+    }>): void;
+    /**
+     * Set base domain on every zoom controller owned by this chart.
+     */
+    setZoomBaseDomain(xMin: number, xMax: number, yMin: number, yMax: number): void;
+    /**
+     * Zoom-controller config for this chart type. Subclasses override to
+     * pin an axis (e.g. bar charts pin the categorical axis). Default:
+     * both axes freely zoomable.
+     */
+    protected getZoomConfig(): ZoomConfig;
+    setColumnSlots(slots: (string | null)[]): void;
+    setViewPivots(groupBy: string[], splitBy: string[]): void;
+    setColumnTypes(schema: Record<string, string>): void;
+    /**
+     * Clear any `domain_mode: "expand"` accumulator state. Driven by
+     * `plugin.draw()` (a fresh `draw` always indicates a view-level
+     * change — viewer config, filters, sorts, etc. — that invalidates
+     * the previously-accumulated extent) and by the worker's
+     * `resetAllZooms` path (user clicked "Reset Zoom"). `plugin.update()`
+     * deliberately does *not* call this — same view, more data, the
+     * accumulator should keep growing. No-op on the base; chart
+     * families that hold accumulator fields override.
+     */
+    resetExpandedDomain(): void;
+    setGroupByTypes(schema: Record<string, string>): void;
+    setColumnsConfig(cfg: Record<string, any>): void;
+    /**
+     * Rebuild {@link _columnFormatters} from `_columnsConfig` +
+     * `_columnTypes`. Called from both `setColumnsConfig` and
+     * `setColumnTypes` since either side of the (config, types) pair
+     * can arrive first depending on the host's restore order. Idempotent.
+     */
+    private _rebuildColumnFormatters;
+    private _compileColumnFormatter;
+    /**
+     * Returns the formatter for `columnName` if one has been configured
+     * (via `column_config_schema` + the user's sidebar choices), else a
+     * type-appropriate fallback for the chart context.
+     *
+     * @param columnName May be a synthetic split-by path
+     *   (`<split_val>|...|<source_col>`); the source column is recovered
+     *   internally before lookup.
+     * @param context `"tick"` returns `undefined` when no per-column
+     *   formatter is configured, so the receiving axis renderer can
+     *   apply its own step-aware default (adaptive date precision from
+     *   tick spacing, K/M/B suffixes for numerics). `"value"` returns
+     *   a precise `Intl.NumberFormat` / `Intl.DateTimeFormat` fallback —
+     *   appropriate for tooltips, legends, overlays where the caller
+     *   invokes the formatter directly and needs a guaranteed function.
+     */
+    getColumnFormatter(columnName: string | null | undefined, context: "tick"): ((v: number) => string) | undefined;
+    getColumnFormatter(columnName: string | null | undefined, context?: "value"): (v: number) => string;
+    setDefaultChartType(chartType: string): void;
+    setFacetConfig(cfg: FacetConfig): void;
+    /**
+     * Apply plugin-scoped global config. Stores `cfg` for later reads
+     * and mirrors the overlapping fields onto adjacent state so deep
+     * render code keeps reading the single struct it already does:
+     *
+     *  - `facet_mode` / `facet_zoom_mode` sync into `_facetConfig` so
+     *    `cartesian-render.ts` (and the treemap/sunburst grid checks)
+     *    keep working unchanged.
+     *  - `series_zoom_mode` toggles the `_autoFitValue` flag declared
+     *    on `CategoricalYChart` ("dynamic" = refit on zoom, "fixed" =
+     *    pinned to full extent). Harmless write on charts that don't
+     *    expose the field.
+     *
+     * Render-path uniform fields (`line_width_px`, `point_size_px`,
+     * `wick_width_px`, `ohlc_line_width_px`) are read directly from
+     * `_pluginConfig` by their respective glyphs on each draw — no
+     * sync needed. Build-time fields (`auto_alt_y_axis`,
+     * `band_inner_frac`, `bar_inner_pad`) are read by the pipeline
+     * inputs in `uploadAndRender`; they take effect on next data load.
+     */
+    setPluginConfig(cfg: PluginConfig): void;
+    /**
+     * Lazily decode the host-supplied theme vars. Subsequent calls hit
+     * the cache until `invalidateTheme()` clears it. Render-path
+     * callers should always read theme values through this method so
+     * the parsed `Theme` (gradient stops, palette, etc.) amortizes
+     * across an entire frame.
+     */
+    _resolveTheme(): Theme;
+    /**
+     * Drop the cached theme so the next `_resolveTheme()` call re-decodes
+     * from `_themeVars`. Wired to `plugin.restyle()` — the host pushes
+     * a fresh var snapshot before invalidating.
+     */
+    invalidateTheme(): void;
+    /**
+     * Install a new view for lazy row fetches. Disposes any prior
+     * fetcher and dismisses the pinned tooltip — the prior pinned
+     * row index has no guaranteed correspondence in the new view
+     * (pivot / filter / sort changes can all reshuffle rows).
+     */
+    setView(view: View): void;
+    /**
+     * Build the chart-specific {@link TooltipCallbacks} object — the
+     * `onHover` / `onLeave` / `onClickPre` / `onPin` / `onDblClick`
+     * surface that mediates between the cursor and chart state.
+     * Subclasses override this; the base returns a no-op pair.
+     */
+    protected tooltipCallbacks(): TooltipCallbacks;
+    /**
+     * Wire the chart's `TooltipController` for virtual-dispatch
+     * `InteractionEvent`s forwarded from the host, and install the
+     * host sink that materializes pinned tooltips and cursor changes
+     * host-side.
+     */
+    attachTooltip(host: HostSink): void;
+    /**
+     * Build a `PerspectiveClickDetail` payload from a per-family
+     * resolved click target. Fetches the source-view row via
+     * `_lazyRows` (returns `row: {}` if the row can't be resolved —
+     * e.g., aggregate / density cells), and concatenates the
+     * `group_by` and `split_by` pivot values into a
+     * `viewer.restore({ filter })`-shaped patch.
+     *
+     * Mirrors the filter-building logic in datagrid's
+     * `getCellConfig` ([packages/viewer-datagrid/src/ts/get_cell_config.ts]),
+     * but operates on `AbstractChart` state rather than a `DatagridModel`.
+     */
+    buildClickDetail(target: {
+        rowIdx: number | null;
+        columnName: string;
+        groupByValues: (string | number | null)[];
+        splitByValues: (string | number | null)[];
+    }): Promise<PerspectiveClickDetail>;
+    /**
+     * Forward a `perspective-click` to the host. No-op when the chart
+     * has not been wired to a host sink (e.g., unit-tested charts).
+     * Synchronous; callers needing ordering with async emits should
+     * chain through `_emitQueue`.
+     */
+    emitUserClick(detail: PerspectiveClickDetail): void;
+    /**
+     * Forward a `perspective-global-filter` to the host. The host
+     * transport materializes a `PerspectiveSelectDetail` from this plus
+     * its cached previous-insert config and dispatches. Synchronous.
+     */
+    emitUserSelect(args: {
+        selected: boolean;
+        row: Record<string, unknown>;
+        column_names: string[];
+        insertConfig: Partial<ViewConfig>;
+    }): void;
+    /**
+     * Convenience: fire both `perspective-click` and
+     * `perspective-global-filter` (`selected: true`) from a resolved
+     * click target. Used by chart families where every click both
+     * "selects" and "filters" (series, heatmap, candlestick, scatter,
+     * treemap-leaf, etc.). Treemap branch / breadcrumb gestures use
+     * the lower-level helpers directly.
+     *
+     * Chains through `_emitQueue` so the row-fetch await can't reorder
+     * this emit behind a follow-up `emitUnselect`.
+     */
+    emitClickAndSelect(target: {
+        rowIdx: number | null;
+        columnName: string;
+        groupByValues: (string | number | null)[];
+        splitByValues: (string | number | null)[];
+    }): Promise<void>;
+    /**
+     * Fire a `perspective-global-filter` with `selected: false`. Used
+     * by treemap / sunburst breadcrumb navigation and by chart-base's
+     * own `setView` when a view change implicitly dismisses any active
+     * pin. Chains through `_emitQueue` so it lands AFTER any in-flight
+     * `emitClickAndSelect`.
+     */
+    emitUnselect(args?: {
+        row?: Record<string, unknown>;
+        column_names?: string[];
+    }): void;
+    /**
+     * Public coalesced render. Routes through the module-level
+     * scheduler so concurrent calls collapse to one `_fullRender` per
+     * RAF and the host blitter receives one bitmap per frame. The
+     * returned promise resolves after this chart's `awaitGpuFence` +
+     * `endFrame` chain — independent of other charts in the same
+     * RAF, which run their fence waits in parallel.
+     *
+     * Every render-triggering caller — upload chunks, zoom / pan,
+     * resize, theme invalidation, host-driven redraws — calls this.
+     * The only sanctioned bypass is `snapshotPng`, which calls
+     * `_fullRender` directly to keep the GL backbuffer intact for
+     * `gl.readPixels`.
+     */
+    requestRender(glManager: WebGLContextManager): Promise<void>;
+    destroy(): void;
+    abstract uploadAndRender(glManager: WebGLContextManager, columns: ColumnDataMap, startRow: number, endRow: number): Promise<void>;
+    abstract _fullRender(glManager: WebGLContextManager): void;
+    /**
+     * Release chart-specific GL/CPU resources. `destroy` calls this.
+     */
+    protected abstract destroyInternal(): void;
+}