@perspective-dev/viewer-charts 5.3.0 → 5.4.0

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

@@ -13,10 +13,14 @@
 import type { Canvas2D, Context2D } from "../charts/canvas-types";
 import type { PlotLayout } from "../layout/plot-layout";
 import type { Theme } from "../theme/theme";
+import {
+    measureTooltipGrid,
+    paintTooltipGrid,
+    DEFAULT_TOOLTIP_STYLE,
+    type TooltipContent,
+    type TooltipStyle,
+} from "./tooltip-grid";
 
-/**
- * Minimal positioning input — PlotLayout satisfies this.
- */
 export interface CssBounds {
     cssWidth: number;
     cssHeight: number;
@@ -25,7 +29,7 @@ export interface CssBounds {
 export interface TooltipCallbacks {
     /**
      * RAF-throttled mouse position in CSS pixels, relative to the GL
-     * canvas (host already subtracted `getBoundingClientRect`).
+     * canvas.
      */
     onHover(mx: number, my: number): void;
 
@@ -35,8 +39,7 @@ export interface TooltipCallbacks {
     onLeave(): void;
 
     /**
-     * Fires on click with mouse position. Return true to consume the click
-     * (skipping the default pin/dismiss flow — used for legend clicks).
+     * Fires on click with mouse position.
      */
     onClickPre?(mx: number, my: number): boolean;
 
@@ -46,93 +49,45 @@ export interface TooltipCallbacks {
     onPin?(mx: number, my: number): void;
 
     /**
-     * Fires on dblclick (treemap drill-up gesture). Optional — charts
-     * that don't bind a handler simply ignore the event.
+     * Fires on dblclick (treemap drill-up gesture).
      */
     onDblClick?(mx: number, my: number): void;
 
     /**
-     * Fires when an active pin is dismissed by a click on the
-     * already-pinned target (the "click again to unpin" gesture in
-     * `dispatchClick`). Chart impls hook this to emit a
-     * `perspective-global-filter` with `selected: false`. Does *not*
-     * fire on the implicit dismiss inside `pin()` that replaces an
-     * existing pin — that path is followed by a fresh `onPin` which
-     * emits its own `selected: true`.
+     * Fires when an active pin is dismissed by a click.
      */
     onUnpin?(): void;
 }
 
 export interface RenderTooltipOptions {
-    /**
-     * Draw a dashed crosshair at `pos`. Used by scatter/line.
-     */
     crosshair?: boolean;
-
-    /**
-     * Draw a ring of `radius` CSS pixels at `pos`. Used to highlight a
-     * hovered point. Omit for bars (where the bar itself highlights).
-     */
     highlightRadius?: number;
+    maxColumnPx?: number;
+    opacity?: number;
 }
 
 /**
- * Side-channel from the chart back to the host's DOM. The chart calls
- * into a sink rather than touching the DOM itself; the host
- * materializes the actual visual (`<div>` for pinned tooltip, cursor
- * mutation on the GL canvas).
- *
- *   - `MessageHostSink` (in worker/) — forwards calls over a
- *                              `postMessage`-shaped channel back to
- *                              the host.
- *   - `DomHostSink` (in host transport) — receives the matching
- *                              envelopes and applies them to the DOM.
- *
- * The controller's `_pinned` flag is the source of truth for whether
- * hover updates are gated; the sink only owns the visual artifact.
+ * Side-channel from the chart back to the host's DOM.
  */
 export interface HostSink {
     pin(
-        lines: string[],
+        grid: TooltipContent,
         pos: { px: number; py: number },
         bounds: CssBounds,
+        style?: TooltipStyle,
     ): void;
     dismiss(): void;
     setCursor(cursor: string): void;
-
-    /**
-     * Forward a `perspective-click` to the host. Optional — only the
-     * worker-bound `MessageHostSink` implements it; `DomHostSink` (the
-     * host-side consumer of pin/dismiss) never sees user-event calls,
-     * so omits the implementation.
-     */
     emitUserClick?(detail: UserClickPayload): void;
-
-    /**
-     * Forward a `perspective-global-filter` to the host with the
-     * `selected: true` / `selected: false` semantics. The host owns the
-     * `removeConfigs` history (mirrors datagrid's
-     * `model._last_insert_configs`); the sink only ships the new state.
-     */
     emitUserSelect?(payload: UserSelectPayload): void;
 }
 
-/**
- * Plain-object payload for `HostSink.emitUserClick`. Matches
- * `PerspectiveClickDetail` byte-for-byte; defined locally to avoid a
- * cycle through `event-detail.ts`.
- */
 export interface UserClickPayload {
     row: Record<string, unknown>;
     column_names: string[];
     config: { filter?: unknown[] };
 }
 
-/**
- * Plain-object payload for `HostSink.emitUserSelect`. The host
- * transport reconstructs a `PerspectiveSelectDetail` class instance
- * from this plus its cached `_lastInsertConfig`.
- */
 export interface UserSelectPayload {
     selected: boolean;
     row: Record<string, unknown>;
@@ -142,13 +97,7 @@ export interface UserSelectPayload {
 
 /**
  * Owns the hover/click/dblclick state machine and the pinned-tooltip
- * lifecycle. The renderer drives this purely through
- * `dispatchHover` / `dispatchLeave` / `dispatchClick` /
- * `dispatchDblClick` — the host's `RawEventForwarder` captures DOM
- * events on the GL canvas and posts them as `InteractionEvent`s.
- *
- * Pinning + cursor changes go through a {@link HostSink} so the actual
- * DOM mutations happen host-side regardless of where the chart runs.
+ * lifecycle.
  */
 export class TooltipController {
     private _callbacks: TooltipCallbacks | null = null;
@@ -162,10 +111,7 @@ export class TooltipController {
     }
 
     /**
-     * Replace the active host sink. Dismisses any existing pin via the
-     * prior sink so we never leak a pinned artifact across resets —
-     * though in practice each chart instance uses one sink for its
-     * lifetime.
+     * Replace the active host sink.
      */
     setHost(sink: HostSink): void {
         if (this._pinned) {
@@ -177,18 +123,14 @@ export class TooltipController {
     }
 
     /**
-     * Forward a cursor change to the host. No-op when no host sink is
-     * installed (chart constructed without a transport).
+     * Forward a cursor change to the host.
      */
     setCursor(cursor: string): void {
         this._host?.setCursor(cursor);
     }
 
     /**
-     * Install the chart's tooltip callbacks. The renderer drives the
-     * controller via `dispatchHover` / `dispatchLeave` /
-     * `dispatchClick` / `dispatchDblClick`; this controller never
-     * touches the DOM directly.
+     * Install the chart's tooltip callbacks.
      */
     attach(callbacks: TooltipCallbacks): void {
         this.detach();
@@ -211,13 +153,7 @@ export class TooltipController {
 
     /**
      * Schedule an `onHover` callback for the given canvas-relative
-     * coords. Coalesces multiple calls within one animation frame so
-     * pointer streams don't backlog the chart's hit-test path.
-     *
-     * Workers ship with `requestAnimationFrame` (DedicatedWorkerGlobalScope
-     * exposes it for OffscreenCanvas painting), so the same coalescer
-     * works in both modes. We fall back to setTimeout if RAF is missing
-     * (e.g. node tests without a polyfill).
+     * coords.
      */
     dispatchHover(mx: number, my: number): void {
         if (this._pinned || !this._callbacks) {
@@ -273,20 +209,19 @@ export class TooltipController {
     }
 
     /**
-     * Pin a tooltip (or replace an active one). Forwards through the
-     * configured sink and flips the controller's pinned flag so hover
-     * dispatch is suppressed until dismissal.
+     * Pin a tooltip (or replace an active one).
      */
     pin(
-        lines: string[],
+        grid: TooltipContent,
         pos: { px: number; py: number },
         bounds: CssBounds,
+        style: TooltipStyle = DEFAULT_TOOLTIP_STYLE,
     ): void {
-        if (lines.length === 0) {
+        if (grid.length === 0) {
             return;
         }
 
-        this._host?.pin(lines, pos, bounds);
+        this._host?.pin(grid, pos, bounds, style);
         this._pinned = true;
     }
 
@@ -298,17 +233,12 @@ export class TooltipController {
 
 /**
  * Paint a canvas tooltip (crosshair, highlight ring, box + text) onto
- * `canvas`. The helper normalizes the 2D context to a DPR-scaled
- * identity transform on entry and restores prior state on exit, so it
- * composes cleanly with other chrome painters that may have already
- * called `initCanvas` on the same canvas — re-applying `scale(dpr,dpr)`
- * blind would double-scale in that case, misplacing the tooltip
- * proportionally to its distance from the origin.
+ * `canvas`.
  */
 export function renderCanvasTooltip(
     canvas: Canvas2D | null,
     pos: { px: number; py: number },
-    lines: string[],
+    grid: TooltipContent,
     layout: PlotLayout,
     theme: Theme,
     dpr: number,
@@ -327,18 +257,12 @@ export function renderCanvasTooltip(
     ctx.setTransform(1, 0, 0, 1, 0, 0);
     ctx.scale(dpr, dpr);
     ctx.font = `11px ${theme.fontFamily}`;
-    const lineHeight = 16;
-    const padding = 8;
-    let maxWidth = 0;
-    for (const line of lines) {
-        const w = ctx.measureText(line).width;
-        if (w > maxWidth) {
-            maxWidth = w;
-        }
-    }
-
-    const boxW = maxWidth + padding * 2;
-    const boxH = lines.length * lineHeight + padding * 2 - 4;
+    const measured = measureTooltipGrid(
+        ctx,
+        grid,
+        options.maxColumnPx ?? DEFAULT_TOOLTIP_STYLE.maxColumnPx,
+    );
+    const { boxW, boxH } = measured;
     let tx = pos.px + 12;
     let ty = pos.py - boxH - 8;
     if (tx + boxW > layout.cssWidth) {
@@ -353,8 +277,6 @@ export function renderCanvasTooltip(
         ty = layout.cssHeight - boxH - 4;
     }
 
-    const hasLines = lines.length > 0;
-
     // Crosshair
     if (options.crosshair) {
         ctx.strokeStyle = theme.tickColor;
@@ -382,25 +304,15 @@ export function renderCanvasTooltip(
         ctx.globalAlpha = 1.0;
     }
 
-    // Box + text are only drawn when we have content. Callers pass an
-    // empty `lines` array while a lazy row fetch is still in flight —
-    // the crosshair / highlight ring above paint immediately so the
-    // hover remains visible, but the tooltip chrome waits for data.
-    if (hasLines) {
-        ctx.fillStyle = theme.tooltipBg;
-        ctx.strokeStyle = theme.tooltipBorder;
-        ctx.lineWidth = 1;
-        ctx.beginPath();
-        ctx.roundRect(tx, ty, boxW, boxH, 4);
-        ctx.fill();
-        ctx.stroke();
-
-        ctx.fillStyle = theme.tooltipText;
-        ctx.textAlign = "left";
-        ctx.textBaseline = "top";
-        for (let i = 0; i < lines.length; i++) {
-            ctx.fillText(lines[i], tx + padding, ty + padding + i * lineHeight);
-        }
+    if (grid.length > 0) {
+        paintTooltipGrid(
+            ctx,
+            measured,
+            tx,
+            ty,
+            theme,
+            options.opacity ?? DEFAULT_TOOLTIP_STYLE.opacity,
+        );
     }
 
     ctx.restore();

package/src/ts/interaction/tooltip-grid.ts

@@ -0,0 +1,187 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import type { Context2D } from "../charts/canvas-types";
+import type { Theme } from "../theme/theme";
+
+export type TooltipRow = string[];
+
+export type TooltipContent = TooltipRow[];
+
+export interface TooltipStyle {
+    opacity: number;
+    maxColumnPx: number;
+}
+
+export const DEFAULT_TOOLTIP_STYLE: TooltipStyle = {
+    opacity: 1.0,
+    maxColumnPx: 160,
+};
+
+export function tooltipStyleOf(cfg: {
+    tooltip_opacity: number;
+    tooltip_max_column_px: number;
+}): TooltipStyle {
+    return {
+        opacity: cfg.tooltip_opacity,
+        maxColumnPx: cfg.tooltip_max_column_px,
+    };
+}
+
+export const NUMERIC_RE =
+    /^[-+−]?[$€£¥]?\s?\d[\d.,  \s]*(?:[eE][-+]?\d+|[KMB%])?$/;
+
+export const TOOLTIP_ROW_HEIGHT = 16;
+export const TOOLTIP_PADDING = 8;
+export const TOOLTIP_COL_GAP = 8;
+
+export interface MeasuredTooltipGrid {
+    rows: string[][];
+
+    colWidths: number[];
+
+    colRightAlign: boolean[];
+
+    boxW: number;
+    boxH: number;
+}
+
+/**
+ * Measure a tooltip grid under the current `ctx.font`.
+ */
+export function measureTooltipGrid(
+    ctx: Context2D,
+    grid: TooltipContent,
+    maxColumnPx: number,
+): MeasuredTooltipGrid {
+    const spanCap = maxColumnPx * 2 + TOOLTIP_COL_GAP;
+    const colWidths: number[] = [];
+    const colNumeric: boolean[] = [];
+    const rows: string[][] = [];
+    let spanWidth = 0;
+
+    for (const row of grid) {
+        if (row.length <= 1) {
+            const text = ellipsize(ctx, row[0] ?? "", spanCap);
+            rows.push([text]);
+            spanWidth = Math.max(spanWidth, ctx.measureText(text).width);
+            continue;
+        }
+
+        const cells: string[] = [];
+        for (let j = 0; j < row.length; j++) {
+            const original = row[j] ?? "";
+            const text = ellipsize(ctx, original, maxColumnPx);
+            cells.push(text);
+            colWidths[j] = Math.max(
+                colWidths[j] ?? 0,
+                ctx.measureText(text).width,
+            );
+            if (j >= 1 && original !== "") {
+                const numeric = NUMERIC_RE.test(original);
+                colNumeric[j] =
+                    colNumeric[j] === undefined
+                        ? numeric
+                        : colNumeric[j] && numeric;
+            }
+        }
+
+        rows.push(cells);
+    }
+
+    let columnsWidth = 0;
+    for (let j = 0; j < colWidths.length; j++) {
+        columnsWidth += colWidths[j] + (j > 0 ? TOOLTIP_COL_GAP : 0);
+    }
+
+    const innerW = Math.max(spanWidth, columnsWidth);
+    return {
+        rows,
+        colWidths,
+        colRightAlign: colWidths.map(
+            (_, j) => (colNumeric[j] ?? false) && j >= 1,
+        ),
+        boxW: innerW + TOOLTIP_PADDING * 2,
+        boxH: grid.length * TOOLTIP_ROW_HEIGHT + TOOLTIP_PADDING * 2 - 4,
+    };
+}
+
+/**
+ * Paint a measured tooltip grid at `(tx, ty)`.
+ */
+export function paintTooltipGrid(
+    ctx: Context2D,
+    measured: MeasuredTooltipGrid,
+    tx: number,
+    ty: number,
+    theme: Theme,
+    opacity: number,
+): void {
+    const { rows, colWidths, colRightAlign, boxW, boxH } = measured;
+
+    ctx.globalAlpha = Math.min(1, Math.max(0, opacity));
+    ctx.fillStyle = theme.tooltipBg;
+    ctx.strokeStyle = theme.tooltipBorder;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.rect(tx, ty, boxW, boxH);
+    ctx.fill();
+    ctx.stroke();
+    ctx.globalAlpha = 1.0;
+
+    ctx.fillStyle = theme.tooltipText;
+    ctx.textBaseline = "top";
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        const rowY = ty + TOOLTIP_PADDING + i * TOOLTIP_ROW_HEIGHT;
+        if (row.length <= 1) {
+            ctx.textAlign = "left";
+            ctx.fillText(row[0], tx + TOOLTIP_PADDING, rowY);
+            continue;
+        }
+
+        let colX = tx + TOOLTIP_PADDING;
+        for (let j = 0; j < row.length; j++) {
+            const width = colWidths[j] ?? 0;
+            if (colRightAlign[j]) {
+                ctx.textAlign = "right";
+                ctx.fillText(row[j], colX + width, rowY);
+            } else {
+                ctx.textAlign = "left";
+                ctx.fillText(row[j], colX, rowY);
+            }
+
+            colX += width + TOOLTIP_COL_GAP;
+        }
+    }
+
+    ctx.textAlign = "left";
+}
+
+export function ellipsize(ctx: Context2D, text: string, maxW: number): string {
+    if (ctx.measureText(text).width <= maxW) {
+        return text;
+    }
+
+    let lo = 0;
+    let hi = text.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (ctx.measureText(text.slice(0, mid) + "…").width <= maxW) {
+            lo = mid;
+        } else {
+            hi = mid - 1;
+        }
+    }
+
+    return text.slice(0, lo) + "…";
+}

package/src/ts/layout/facet-grid.ts

@@ -50,6 +50,13 @@ export interface FacetGridOptions {
      */
     hasLegend?: boolean;
 
+    /**
+     * Width of the legend gutter when `hasLegend` is set. Defaults to
+     * the historical `LEGEND_GUTTER` (96). Callers resolve this from
+     * `plugin_config.legend_width_px` via `legendSidebarWidth`.
+     */
+    legendWidth?: number;
+
     /** Axis-label allowance (consumed only when the corresponding axis
      *  mode produces a gutter — outer band or per-cell). */
     hasXLabel?: boolean;
@@ -220,7 +227,7 @@ export function buildFacetGrid(
     }
 
     const titleBand = opts.titleBand ?? TITLE_BAND_DEFAULT;
-    const legendW = opts.hasLegend ? LEGEND_GUTTER : 0;
+    const legendW = opts.hasLegend ? (opts.legendWidth ?? LEGEND_GUTTER) : 0;
 
     const xMode: AxisMode = opts.xAxis ?? "cell";
     const yMode: AxisMode = opts.yAxis ?? "cell";

package/src/ts/layout/ticks.ts

@@ -69,6 +69,18 @@ export function computeNiceTicks(
     return ticks;
 }
 
+export function stepTickFormatter(
+    isDate: boolean | undefined,
+    ticks: number[] | null | undefined,
+): (v: number) => string {
+    if (!isDate) {
+        return formatTickValue;
+    }
+
+    const step = ticks && ticks.length > 1 ? ticks[1] - ticks[0] : 0;
+    return (v: number) => formatDateTickValue(v, step);
+}
+
 /**
  * Format a numeric tick value for display.
  * Uses K/M/B suffixes for large numbers, fixed decimals for small.

package/src/ts/map/tile-loader.ts

@@ -119,7 +119,22 @@ export class TileLoader {
         url: string,
         signal: AbortSignal,
     ): Promise<ImageBitmap | null> {
-        const resp = await fetch(url, { signal });
+        // Explicit same-origin `referrer`: in worker mode this code runs
+        // in a blob-URL worker, whose client URL is unreferable — its
+        // fetches carry NO `Referer` under ANY document Referrer-Policy
+        // (verified empirically, Chromium 139). Tile providers gate on
+        // it: OSM serves "403r — referer is required" blocked TILES
+        // (HTTP 200, error drawn into the image; see the OSM wiki's
+        // Blocked_tiles page) to referer-less requests. An explicit
+        // same-origin referrer serializes to the page origin under the
+        // default policy, which is exactly the identification those
+        // providers ask for. Opaque/non-http origins (`"null"`) are
+        // skipped — the option would throw.
+        const referrer = self.origin?.startsWith("http")
+            ? `${self.origin}/`
+            : undefined;
+
+        const resp = await fetch(url, { signal, referrer });
         if (!resp.ok) {
             return null;
         }