@perspective-dev/viewer-charts 4.5.0 → 4.5.1

package/src/ts/charts/treemap/treemap-render.ts

@@ -22,16 +22,16 @@ import {
 import { Theme } from "../../theme/theme";
 import { resolvePalette, type Vec3 } from "../../theme/palette";
 import { type GradientStop } from "../../theme/gradient";
-import { renderLegend, renderCategoricalLegend } from "../../axis/legend";
-import { PlotLayout } from "../../layout/plot-layout";
 import { buildFacetGrid } from "../../layout/facet-grid";
 import { leafColor, leafRGBA, luminance } from "../common/leaf-color";
 import treemapVert from "../../shaders/treemap.vert.glsl";
 import treemapFrag from "../../shaders/treemap.frag.glsl";
+import { compileProgram } from "../../webgl/program-cache";
 import { withChromeCache } from "../common/chrome-cache";
 import { wrapLabel } from "../../axis/label-geometry";
 import {
     renderBreadcrumbs as renderTreeBreadcrumbs,
+    renderTreeColorLegend,
     renderTreeTooltip,
 } from "../common/tree-chrome";
 
@@ -111,16 +111,18 @@ export function renderTreemapFrame(
     }
 
     if (!chart._program) {
-        chart._program = glManager.shaders.getOrCreate(
+        const compiled = compileProgram<
+            { program: WebGLProgram } & NonNullable<TreemapChart["_locations"]>
+        >(
+            glManager,
             "treemap",
             treemapVert,
             treemapFrag,
+            ["u_resolution"],
+            ["a_position", "a_color"],
         );
-        chart._locations = {
-            u_resolution: gl.getUniformLocation(chart._program, "u_resolution"),
-            a_position: gl.getAttribLocation(chart._program, "a_position"),
-            a_color: gl.getAttribLocation(chart._program, "a_color"),
-        };
+        chart._program = compiled.program;
+        chart._locations = compiled;
     }
 
     const theme = chart._resolveTheme();
@@ -648,44 +650,15 @@ function drawStaticChrome(
         renderTreeBreadcrumbs(chart, ctx, cssWidth, fontFamily, textColor);
     }
 
-    // Legend: numeric mode → gradient bar; series mode with 2+ unique
-    // labels → categorical swatches. Empty mode (and single-label series)
-    // suppress the legend entirely.
-    if (chart._colorMode === "series" && chart._uniqueColorLabels.size > 1) {
-        const legendLayout = new PlotLayout(cssWidth, cssHeight, {
-            hasXLabel: false,
-            hasYLabel: false,
-            hasLegend: true,
-        });
-        renderCategoricalLegend(
-            canvas,
-            legendLayout,
-            chart._uniqueColorLabels,
-            palette,
-            theme,
-        );
-    } else if (
-        chart._colorMode === "numeric" &&
-        chart._colorMin < chart._colorMax
-    ) {
-        const legendLayout = new PlotLayout(cssWidth, cssHeight, {
-            hasXLabel: false,
-            hasYLabel: false,
-            hasLegend: true,
-        });
-        renderLegend(
-            canvas,
-            legendLayout,
-            {
-                min: chart._colorMin,
-                max: chart._colorMax,
-                label: chart._colorName,
-            },
-            stops,
-            theme,
-            chart.getColumnFormatter(chart._colorName, "value"),
-        );
-    }
+    renderTreeColorLegend(
+        chart,
+        canvas,
+        palette,
+        stops,
+        theme,
+        cssWidth,
+        cssHeight,
+    );
 
     // Per-facet titles (rendered over the layout; painted in the static
     // chrome bitmap so they appear alongside leaf labels).

package/src/ts/charts/treemap/treemap.ts

@@ -12,7 +12,7 @@
 
 import type { ColumnDataMap } from "../../data/view-reader";
 import type { WebGLContextManager } from "../../webgl/context-manager";
-import { TreeChartBase } from "../common/tree-chart";
+import { TreeChartBase, firstNonMetadataColumn } from "../common/tree-chart";
 import { NULL_NODE } from "../common/node-store";
 import {
     type BreadcrumbRegion,
@@ -34,21 +34,6 @@ export interface TreemapLocations {
     a_color: number;
 }
 
-/**
- * Sentinel fallback for the Size slot when the user hasn't picked one:
- * use the first non-metadata column in the incoming view. Treemap
- * still needs *some* numeric-ish column to size rects.
- */
-function firstNonMetadataColumn(columns: ColumnDataMap): string {
-    for (const k of columns.keys()) {
-        if (!k.startsWith("__")) {
-            return k;
-        }
-    }
-
-    return "";
-}
-
 /**
  * Treemap chart. Shares tree storage + streaming-pipeline + color-mode
  * state with `TreeChartBase`; adds rectangular layout + WebGL quad

package/src/ts/interaction/host-sink-message.ts

@@ -10,6 +10,13 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+import type {
+    DismissTooltipMsg,
+    PinTooltipMsg,
+    SetCursorMsg,
+    UserClickMsg,
+    UserSelectMsg,
+} from "../transport/protocol";
 import type {
     CssBounds,
     HostSink,
@@ -18,29 +25,24 @@ import type {
 } from "./tooltip-controller";
 
 /**
- * Envelope shape sent by `MessageHostSink`. The transport translates
- * each one into a corresponding `WorkerMsg` (`pinTooltip` /
- * `dismissTooltip` / `setCursor` / `userClick` / `userSelect`).
+ * The subset of `WorkerMsg`s that flow chart → host through a
+ * `MessageHostSink`. Identical to the worker-side post payloads so the
+ * sink can ship them straight to `WorkerRenderer.post` with no
+ * intermediate translation.
  */
 export type HostSinkEnvelope =
-    | {
-          kind: "pin";
-          payload: {
-              lines: string[];
-              pos: { px: number; py: number };
-              bounds: CssBounds;
-          };
-      }
-    | { kind: "dismiss" }
-    | { kind: "setCursor"; cursor: string }
-    | { kind: "userClick"; payload: UserClickPayload }
-    | { kind: "userSelect"; payload: UserSelectPayload };
+    | PinTooltipMsg
+    | DismissTooltipMsg
+    | SetCursorMsg
+    | UserClickMsg
+    | UserSelectMsg;
 
 /**
  * `HostSink` that posts pin / dismiss / setCursor / user-event intents
- * over a `postMessage`-style channel. The host-side transport listens
- * for these envelopes and drives a `DomHostSink` for pin/dismiss and
- * dispatches `CustomEvent`s on the viewer for user events.
+ * over a `postMessage`-style channel as `WorkerMsg`s. The host-side
+ * transport listens for these and drives a `DomHostSink` for
+ * pin/dismiss and dispatches `CustomEvent`s on the viewer for user
+ * events.
  */
 export class MessageHostSink implements HostSink {
     private _send: (msg: HostSinkEnvelope) => void;
@@ -54,11 +56,11 @@ export class MessageHostSink implements HostSink {
         pos: { px: number; py: number },
         bounds: CssBounds,
     ): void {
-        this._send({ kind: "pin", payload: { lines, pos, bounds } });
+        this._send({ kind: "pinTooltip", lines, pos, bounds });
     }
 
     dismiss(): void {
-        this._send({ kind: "dismiss" });
+        this._send({ kind: "dismissTooltip" });
     }
 
     setCursor(cursor: string): void {
@@ -66,10 +68,19 @@ export class MessageHostSink implements HostSink {
     }
 
     emitUserClick(payload: UserClickPayload): void {
-        this._send({ kind: "userClick", payload });
+        // `UserClickPayload` is structurally identical to
+        // `PerspectiveClickDetail`; the cast carries the `config`
+        // field's looser inner shape without affecting runtime data.
+        this._send({ kind: "userClick", detail: payload as any });
     }
 
     emitUserSelect(payload: UserSelectPayload): void {
-        this._send({ kind: "userSelect", payload });
+        this._send({
+            kind: "userSelect",
+            selected: payload.selected,
+            row: payload.row,
+            column_names: payload.column_names,
+            insertConfig: payload.insertConfig as any,
+        });
     }
 }

package/src/ts/interaction/raw-event-forwarder.ts

@@ -13,16 +13,15 @@
 import type { InteractionEvent } from "../transport/protocol";
 
 /**
- * Worker-mode counterpart to {@link ZoomRouter}. Captures wheel /
- * pointer events on the GL canvas, normalizes coords to canvas-relative
- * CSS pixels, and emits semantic {@link InteractionEvent}s to the
- * Renderer over its transport. The Renderer (running in a Web Worker)
- * owns the `ZoomController`s and runs the actual hit-test + apply
- * logic — see `applyWheel` / `applyPan` in `zoom-router.ts`.
+ * Captures wheel / pointer events on the GL canvas, normalizes coords
+ * to canvas-relative CSS pixels, and emits semantic
+ * {@link InteractionEvent}s to the Renderer over its transport. The
+ * Renderer owns the `ZoomController`s and runs the actual hit-test +
+ * apply logic — see `applyWheel` / `applyPan` in `zoom-router.ts`.
  *
  * Pointer capture is set on `pointerdown` and released on `pointerup`
  * so drags continue to deliver `pointermove` events when the cursor
- * leaves the canvas, matching the in-process `ZoomRouter` behavior.
+ * leaves the canvas.
  */
 export class RawEventForwarder {
     private _element: HTMLElement | null = null;
@@ -47,11 +46,10 @@ export class RawEventForwarder {
             const mx = e.clientX - rect.left;
             const my = e.clientY - rect.top;
 
-            // Match `ZoomRouter`: only consume the wheel event if the
-            // cursor is over the canvas. `preventDefault` is fired
-            // unconditionally so the page does not scroll while the
-            // chart is hovered — the worker may still no-op if the
-            // cursor is outside any facet's plot rect.
+            // `preventDefault` is fired unconditionally so the page
+            // does not scroll while the chart is hovered — the worker
+            // may still no-op if the cursor is outside any facet's
+            // plot rect.
             e.preventDefault();
             emit({ type: "wheel", mx, my, deltaY: e.deltaY });
         };

package/src/ts/interaction/zoom-controller.ts

@@ -108,6 +108,15 @@ export class ZoomController {
     private _lockAxis: "x" | "y" | null = null;
     private _lockAspect = false;
 
+    // Opt-in "pin" flags. When set, `setBaseDomain` preserves the
+    // axis's *absolute* visible center across a base swap — the
+    // pre-existing rebase math. Default-cleared: data updates "follow"
+    // (preserve normalized translate, so the visible window tracks the
+    // data fractionally). Wire to a paused-frame review feature when
+    // one exists; no current caller flips these.
+    private _xPinned = false;
+    private _yPinned = false;
+
     private _element: HTMLElement | null = null;
     private _layout: PlotLayout | null = null;
     private _onUpdate: (() => void) | null = null;
@@ -121,9 +130,8 @@ export class ZoomController {
     private _onPointerMove: ((e: PointerEvent) => void) | null = null;
     private _onPointerUp: ((e: PointerEvent) => void) | null = null;
 
-    // Per-controller mutators used by `ZoomRouter` to apply wheel/pan
-    // events without going through `attach`. Live below under "Router
-    // helpers" for the facet-aware zoom path.
+    // Per-controller mutators used by `applyWheel` / `applyPan`
+    // (zoom-router.ts) for the facet-aware zoom path.
     get lockedAxis(): "x" | "y" | null {
         return this._lockAxis;
     }
@@ -159,28 +167,27 @@ export class ZoomController {
     }
 
     /**
-     * Update the base (full-data) domain that this controller's
-     * normalized translate is interpreted against, while preserving
-     * the *absolute* center of any user-applied pan.
+     * Update the base (full-data) domain. Each axis is handled
+     * independently:
      *
-     * `_normTX` / `_normTY` are stored as fractions of the base
-     * range, not absolute coordinates. A naive "swap base, keep
-     * normTranslate" update reinterprets the same fraction against a
-     * new range, so when an external `draw()` updates the extent
-     * (via `processCartesianChunk` → `setZoomBaseDomain`) the user's
-     * pan-offset visible center jumps to a different absolute
-     * position. With concurrent pan events feeding in offsets that
-     * were computed against the old base, the jump can project the
-     * visible center past the data entirely, leaving `_fullRender`
-     * to draw zero glyphs onto a freshly-cleared canvas — a blank
-     * bitmap reaches the host as a flicker.
+     *  - If the axis is at default (no user pan or zoom on this axis),
+     *    just swap the new base in — no further math needed.
+     *  - If the axis has been explicitly *pinned* (`pinAxis("x" | "y")`),
+     *    preserve its *absolute* visible center across the swap:
+     *    re-solve `_normT` so the data-space center is unchanged.
+     *    This is paused-frame-review semantics — the user has marked a
+     *    region of interest and wants it to stay put even as new data
+     *    flows in. No current caller pins, but the API is here so the
+     *    default rule below doesn't bake the choice in.
+     *  - Otherwise (the default — "follow"): keep `_normT` as-is and
+     *    just swap the new base. The visible window's *fractional*
+     *    position is preserved, so sliding windows slide with the data
+     *    and extending windows grow proportionally with the data.
      *
-     * When the user is in default state (no pan, no zoom — fresh
-     * controller, or just-reset), no rebase is needed; just swap the
-     * base and let the chart auto-fit to the new data. Otherwise
-     * recompute `_normTX` / `_normTY` so the visible center stays at
-     * the same absolute (data-coordinate) position before and after
-     * the swap.
+     * Per-axis handling matters because `_scaleX/_normTX` and
+     * `_scaleY/_normTY` are independent. A user who panned X to scroll
+     * through time should not force Y onto the rebase path — Y data
+     * updates should still flow through cleanly.
      */
     setBaseDomain(
         xMin: number,
@@ -188,32 +195,57 @@ export class ZoomController {
         yMin: number,
         yMax: number,
     ): void {
-        if (this.isDefault()) {
+        const newRangeX = xMax - xMin;
+        if (this.isXDefault() || !this._xPinned) {
+            this._baseXMin = xMin;
+            this._baseXMax = xMax;
+        } else {
+            const oldRangeX = this._baseXMax - this._baseXMin;
+            const oldCx =
+                (this._baseXMin + this._baseXMax) / 2 +
+                this._normTX * oldRangeX;
             this._baseXMin = xMin;
             this._baseXMax = xMax;
+            this._normTX =
+                newRangeX > 0 ? (oldCx - (xMin + xMax) / 2) / newRangeX : 0;
+        }
+
+        const newRangeY = yMax - yMin;
+        if (this.isYDefault() || !this._yPinned) {
+            this._baseYMin = yMin;
+            this._baseYMax = yMax;
+        } else {
+            const oldRangeY = this._baseYMax - this._baseYMin;
+            const oldCy =
+                (this._baseYMin + this._baseYMax) / 2 +
+                this._normTY * oldRangeY;
             this._baseYMin = yMin;
             this._baseYMax = yMax;
-            return;
+            this._normTY =
+                newRangeY > 0 ? (oldCy - (yMin + yMax) / 2) / newRangeY : 0;
         }
+    }
 
-        const oldRangeX = this._baseXMax - this._baseXMin;
-        const oldRangeY = this._baseYMax - this._baseYMin;
-        const oldCx =
-            (this._baseXMin + this._baseXMax) / 2 + this._normTX * oldRangeX;
-        const oldCy =
-            (this._baseYMin + this._baseYMax) / 2 + this._normTY * oldRangeY;
-
-        this._baseXMin = xMin;
-        this._baseXMax = xMax;
-        this._baseYMin = yMin;
-        this._baseYMax = yMax;
+    /**
+     * Mark an axis as "pinned" so subsequent `setBaseDomain` calls
+     * preserve its *absolute* visible center (paused-frame-review
+     * semantics). Default-cleared on construction; both axes follow
+     * data growth fractionally until explicitly pinned.
+     */
+    pinAxis(axis: "x" | "y"): void {
+        if (axis === "x") {
+            this._xPinned = true;
+        } else {
+            this._yPinned = true;
+        }
+    }
 
-        const newRangeX = xMax - xMin;
-        const newRangeY = yMax - yMin;
-        this._normTX =
-            newRangeX > 0 ? (oldCx - (xMin + xMax) / 2) / newRangeX : 0;
-        this._normTY =
-            newRangeY > 0 ? (oldCy - (yMin + yMax) / 2) / newRangeY : 0;
+    unpinAxis(axis: "x" | "y"): void {
+        if (axis === "x") {
+            this._xPinned = false;
+        } else {
+            this._yPinned = false;
+        }
     }
 
     /**
@@ -234,13 +266,16 @@ export class ZoomController {
         }
     }
 
+    isXDefault(): boolean {
+        return this._scaleX === 1 && this._normTX === 0;
+    }
+
+    isYDefault(): boolean {
+        return this._scaleY === 1 && this._normTY === 0;
+    }
+
     isDefault(): boolean {
-        return (
-            this._scaleX === 1 &&
-            this._scaleY === 1 &&
-            this._normTX === 0 &&
-            this._normTY === 0
-        );
+        return this.isXDefault() && this.isYDefault();
     }
 
     getVisibleDomain(): {
@@ -300,14 +335,15 @@ export class ZoomController {
                 return;
             }
 
-            // Data coordinate under cursor before zoom
-            const domain = this.getVisibleDomain();
-            const dataX =
-                domain.xMin +
-                ((mouseX - plot.x) / plot.width) * (domain.xMax - domain.xMin);
-            const dataY =
-                domain.yMax -
-                ((mouseY - plot.y) / plot.height) * (domain.yMax - domain.yMin);
+            // Cursor position as a fraction of the plot rect — the
+            // anchor point that should stay visually fixed across the
+            // zoom mutation below. `fracY` is 0 at top, 1 at bottom
+            // (screen coords); Y data axis is inverted, hence the
+            // `0.5 - fracY` form below.
+            const fracX = (mouseX - plot.x) / plot.width;
+            const fracY = (mouseY - plot.y) / plot.height;
+            const oldScaleX = this._scaleX;
+            const oldScaleY = this._scaleY;
 
             // Zoom factor — skip the locked axis so its scale stays
             // pinned at 1.
@@ -326,25 +362,26 @@ export class ZoomController {
                 );
             }
 
-            // Adjust translate so the data point under cursor stays put
-            const newDomain = this.getVisibleDomain();
-            const newDataX =
-                newDomain.xMin +
-                ((mouseX - plot.x) / plot.width) *
-                    (newDomain.xMax - newDomain.xMin);
-            const newDataY =
-                newDomain.yMax -
-                ((mouseY - plot.y) / plot.height) *
-                    (newDomain.yMax - newDomain.yMin);
-
-            const bxRange = this._baseXMax - this._baseXMin;
-            const byRange = this._baseYMax - this._baseYMin;
-            if (this._lockAxis !== "x" && bxRange > 0) {
-                this._normTX += (dataX - newDataX) / bxRange;
+            // Cursor-anchored zoom: keep the data point under the
+            // cursor visually fixed. Derivation, for X:
+            //   dataX(scale) = mid + normTX*baseRange
+            //                + (fracX - 0.5) * baseRange/scale
+            // After mutating scale (normTX unchanged), the cursor data
+            // coord shifts. Re-anchoring is `normTX +=
+            // (oldDataX - newDataX) / baseRange`; the `baseRange`
+            // terms cancel to:
+            //   normTXDelta = (fracX - 0.5) * (1/oldScale - 1/newScale)
+            // Base-independent — a concurrent `setBaseDomain` mid-
+            // handler can't corrupt the anchor math. Y axis is screen-
+            // inverted, hence `(0.5 - fracY)`.
+            if (this._lockAxis !== "x" && oldScaleX !== this._scaleX) {
+                this._normTX +=
+                    (fracX - 0.5) * (1 / oldScaleX - 1 / this._scaleX);
             }
 
-            if (this._lockAxis !== "y" && byRange > 0) {
-                this._normTY += (dataY - newDataY) / byRange;
+            if (this._lockAxis !== "y" && oldScaleY !== this._scaleY) {
+                this._normTY +=
+                    (0.5 - fracY) * (1 / oldScaleY - 1 / this._scaleY);
             }
 
             this._onUpdate!();
@@ -379,19 +416,19 @@ export class ZoomController {
             this._lastPointerX = e.clientX;
             this._lastPointerY = e.clientY;
 
-            const domain = this.getVisibleDomain();
+            // Pan as a fraction is `dx / (plotWidth * scaleX)` —
+            // independent of the current base range. The chained form
+            // (`pixels → data delta → fraction-of-base`) cancels the
+            // `baseRange` terms algebraically; computing the cancelled
+            // form directly means a concurrent `setBaseDomain` swap
+            // mid-gesture cannot corrupt the pan math.
             const plot = this._layout!.plotRect;
-            const dataPerPixelX = (domain.xMax - domain.xMin) / plot.width;
-            const dataPerPixelY = (domain.yMax - domain.yMin) / plot.height;
-
-            const bxRange = this._baseXMax - this._baseXMin;
-            const byRange = this._baseYMax - this._baseYMin;
-            if (this._lockAxis !== "x" && bxRange > 0) {
-                this._normTX -= (dx * dataPerPixelX) / bxRange;
+            if (this._lockAxis !== "x" && plot.width > 0) {
+                this._normTX -= dx / (plot.width * this._scaleX);
             }
 
-            if (this._lockAxis !== "y" && byRange > 0) {
-                this._normTY += (dy * dataPerPixelY) / byRange;
+            if (this._lockAxis !== "y" && plot.height > 0) {
+                this._normTY += dy / (plot.height * this._scaleY);
             }
 
             this._onUpdate!();