@perspective-dev/viewer-charts 5.3.0 → 5.4.0

package/src/ts/charts/cartesian/glyphs/density.ts

@@ -309,12 +309,12 @@ export class DensityGlyph implements Glyph {
     buildTooltipLines(
         chart: CartesianChart,
         flatIdx: number,
-    ): Promise<string[]> {
+    ): Promise<string[][]> {
         return buildPointRowTooltipLines(chart, flatIdx);
     }
 
     tooltipOptions() {
-        return { crosshair: true, highlightRadius: 0 };
+        return { crosshair: true, highlightRadius: 0, axisIndicators: true };
     }
 
     destroy(chart: CartesianChart): void {

package/src/ts/charts/cartesian/glyphs/lines.ts

@@ -19,6 +19,7 @@ import {
     getInstancing,
 } from "../../../webgl/instanced-attrs";
 import { compileProgram } from "../../../webgl/program-cache";
+import { colorRangePivot } from "../../../theme/gradient";
 import { formatTickValue, formatDateTickValue } from "../../../layout/ticks";
 import lineVert from "../../../shaders/line.vert.glsl";
 import lineFrag from "../../../shaders/line.frag.glsl";
@@ -124,17 +125,17 @@ export class LineGlyph implements Glyph {
     async buildTooltipLines(
         chart: CartesianChart,
         flatIdx: number,
-    ): Promise<string[]> {
-        const lines: string[] = [];
+    ): Promise<string[][]> {
+        const grid: string[][] = [];
         if (!chart._xData || !chart._yData) {
-            return lines;
+            return grid;
         }
 
         if (chart._splitGroups.length > 0 && chart._seriesCapacity > 0) {
             const seriesIdx = Math.floor(flatIdx / chart._seriesCapacity);
             const sg = chart._splitGroups[seriesIdx];
             if (sg) {
-                lines.push(sg.prefix);
+                grid.push([sg.prefix]);
             }
         }
 
@@ -146,20 +147,20 @@ export class LineGlyph implements Glyph {
         const xFormatted = xIsDate
             ? formatDateTickValue(xVal)
             : formatTickValue(xVal);
-        lines.push(`${chart._xLabel || "Row"}: ${xFormatted}`);
+        grid.push([chart._xLabel || "Row", xFormatted]);
 
         const yType = chart._columnTypes[chart._yLabel] || "";
         const yIsDate = yType === "date" || yType === "datetime";
         const yFormatted = yIsDate
             ? formatDateTickValue(yVal)
             : formatTickValue(yVal);
-        lines.push(`${chart._yLabel}: ${yFormatted}`);
+        grid.push([chart._yLabel, yFormatted]);
 
-        return lines;
+        return grid;
     }
 
     tooltipOptions() {
-        return { crosshair: true, highlightRadius: 5 };
+        return { crosshair: true, highlightRadius: 5, axisIndicators: true };
     }
 
     destroy(chart: CartesianChart): void {
@@ -195,10 +196,13 @@ function bindLineState(
     gl.uniformMatrix4fv(cache.u_projection, false, projection);
     gl.uniform2f(cache.u_resolution, gl.canvas.width, gl.canvas.height);
     gl.uniform1f(cache.u_line_width, chart._pluginConfig.line_width_px * dpr);
-    if (chart._colorMin < chart._colorMax) {
-        gl.uniform2f(cache.u_color_range, chart._colorMin, chart._colorMax);
-    } else {
+    if (chart._colorMin >= chart._colorMax) {
         gl.uniform2f(cache.u_color_range, 0.0, 0.0);
+    } else if (chart._colorName && !chart._colorIsString) {
+        const [lo, hi] = colorRangePivot(chart._colorMin, chart._colorMax);
+        gl.uniform2f(cache.u_color_range, lo, hi);
+    } else {
+        gl.uniform2f(cache.u_color_range, chart._colorMin, chart._colorMax);
     }
 
     bindGradientTexture(

package/src/ts/charts/cartesian/glyphs/points.ts

@@ -14,6 +14,7 @@ import type { WebGLContextManager } from "../../../webgl/context-manager";
 import type { CartesianChart } from "../cartesian";
 import type { Glyph } from "../glyph";
 import { bindGradientTexture } from "../../../webgl/gradient-texture";
+import { colorRangePivot } from "../../../theme/gradient";
 import { compileProgram } from "../../../webgl/program-cache";
 import { buildPointRowTooltipLines } from "../tooltip-lines";
 import scatterVert from "../../../shaders/scatter.vert.glsl";
@@ -130,12 +131,12 @@ export class PointGlyph implements Glyph {
     buildTooltipLines(
         chart: CartesianChart,
         flatIdx: number,
-    ): Promise<string[]> {
+    ): Promise<string[][]> {
         return buildPointRowTooltipLines(chart, flatIdx);
     }
 
     tooltipOptions() {
-        return { crosshair: true, highlightRadius: 6 };
+        return { crosshair: true, highlightRadius: 6, axisIndicators: true };
     }
 
     destroy(_chart: CartesianChart): void {
@@ -155,10 +156,13 @@ function setUniforms(
     gl.uniformMatrix4fv(cache.u_projection, false, projection);
     gl.uniform1f(cache.u_point_size, chart._pluginConfig.point_size_px * dpr);
 
-    if (chart._colorMin < chart._colorMax) {
-        gl.uniform2f(cache.u_color_range, chart._colorMin, chart._colorMax);
-    } else {
+    if (chart._colorMin >= chart._colorMax) {
         gl.uniform2f(cache.u_color_range, 0.0, 0.0);
+    } else if (chart._colorName && !chart._colorIsString) {
+        const [lo, hi] = colorRangePivot(chart._colorMin, chart._colorMax);
+        gl.uniform2f(cache.u_color_range, lo, hi);
+    } else {
+        gl.uniform2f(cache.u_color_range, chart._colorMin, chart._colorMax);
     }
 
     if (chart._sizeMin < chart._sizeMax) {

package/src/ts/charts/cartesian/tooltip-lines.ts

@@ -24,22 +24,22 @@ import type { CartesianChart } from "./cartesian";
 export async function buildPointRowTooltipLines(
     chart: CartesianChart,
     flatIdx: number,
-): Promise<string[]> {
-    const lines: string[] = [];
+): Promise<string[][]> {
+    const grid: string[][] = [];
     if (!chart._rowIndexData || !chart._lazyRows) {
-        return lines;
+        return grid;
     }
 
     const rowIdx = chart._rowIndexData[flatIdx];
     if (rowIdx < 0) {
-        return lines;
+        return grid;
     }
 
     if (chart._splitGroups.length > 0 && chart._seriesCapacity > 0) {
         const seriesIdx = Math.floor(flatIdx / chart._seriesCapacity);
         const sg = chart._splitGroups[seriesIdx];
         if (sg?.prefix) {
-            lines.push(sg.prefix);
+            grid.push([sg.prefix]);
         }
     }
 
@@ -70,11 +70,11 @@ export async function buildPointRowTooltipLines(
 
         if (typeof value === "number") {
             const formatted = chart.getColumnFormatter(colName, "value")(value);
-            lines.push(`${displayName}: ${formatted}`);
+            grid.push([displayName, formatted]);
         } else {
-            lines.push(`${displayName}: ${value}`);
+            grid.push([displayName, String(value)]);
         }
     }
 
-    return lines;
+    return grid;
 }

package/src/ts/charts/chart-base.ts

@@ -21,7 +21,11 @@ import {
 } from "@perspective-dev/viewer/src/ts/column-format.js";
 import type { ColumnDataMap } from "../data/view-reader";
 import { LazyRowFetcher } from "../data/lazy-row";
-import { formatTickValue, formatDateTickValue } from "../layout/ticks";
+import {
+    CHART_DATE_DEFAULTS,
+    CHART_DATETIME_DEFAULTS,
+    CHART_NUMBER_DEFAULTS,
+} from "../plugin/format-defaults";
 import type { WebGLContextManager } from "../webgl/context-manager";
 import {
     ZoomController,
@@ -41,52 +45,37 @@ import {
     type UserClickPayload,
     type UserSelectPayload,
 } from "../interaction/tooltip-controller";
+import { LegendController } from "../interaction/legend-controller";
 import type { PerspectiveClickDetail } from "../event-detail";
 import type { ViewConfig } from "@perspective-dev/client";
 import { resolveThemeFromVars, type Theme } from "../theme/theme";
 import { applyColumnColorOverrides } from "../theme/overrides";
 import { requestRender as scheduleRender } from "../render/scheduler";
 
-// TODO I don't know if this is the behavior we want. On the plus side, this
-// ad-hoc formatter scales well to small and large data ranges, making a good
-// guess at the right format without user input. On the minus side, this
-// behavior is inconsistent with datagrid and the rest of the app, and the ad-hoc
-// surprising behavior when overriding one field in `number_format` and suddenly
-// the entire formatter is replaced.
-const REGRESSION_BEHAVIOR = true;
-
 /**
- * Locale-aware fallback formatter applied to numeric tooltip / legend
- * values when the column has no `number_format` configured. Two
- * fractional digits matches the legacy datagrid default and gives
- * tooltips a stable display width.
+ * Fallback formatter applied to numeric tooltip / legend values when the
+ * column has no `number_format` configured.
  */
 const DEFAULT_VALUE_FORMATTER: (v: number) => string = ((): ((
     v: number,
 ) => string) => {
-    if (REGRESSION_BEHAVIOR) {
-        return formatTickValue;
-    } else {
-        const intl = createNumberFormatter("float");
-        return (v) => intl.format(v);
-    }
+    const intl = createNumberFormatter(
+        "float",
+        undefined,
+        CHART_NUMBER_DEFAULTS,
+    );
+    return (v) => intl.format(v);
 })();
 
 /**
- * Locale-aware fallback formatter for datetime tooltip / legend values
- * when the column has no `date_format` configured. Uses the locale
- * default (no `dateStyle` / `timeStyle`) to match what most users
- * expect from an `Intl.DateTimeFormat()` constructed with no options.
+ * Fallback formatter for datetime tooltip / legend values when the
+ * column has no `date_format` configured.
  */
 const DEFAULT_DATETIME_FORMATTER: (v: number) => string = ((): ((
     v: number,
 ) => string) => {
-    if (REGRESSION_BEHAVIOR) {
-        return formatDateTickValue;
-    } else {
-        const intl = createDatetimeFormatter();
-        return (v) => intl.format(v);
-    }
+    const intl = createDatetimeFormatter(undefined, CHART_DATETIME_DEFAULTS);
+    return (v) => intl.format(v);
 })();
 
 /**
@@ -238,6 +227,7 @@ export abstract class AbstractChart implements ChartImplementation {
      */
     _pluginConfig: PluginConfig = { ...DEFAULT_PLUGIN_CONFIG };
 
+    _legend = new LegendController();
     _tooltip = new TooltipController();
 
     /**
@@ -495,7 +485,11 @@ export abstract class AbstractChart implements ChartImplementation {
                 return undefined;
             }
 
-            const intl = createNumberFormatter(type, numberFormat);
+            const intl = createNumberFormatter(
+                type,
+                numberFormat,
+                CHART_NUMBER_DEFAULTS,
+            );
             return (v) => intl.format(v);
         }
 
@@ -505,7 +499,10 @@ export abstract class AbstractChart implements ChartImplementation {
                 return undefined;
             }
 
-            const intl = createDatetimeFormatter(dateFormat);
+            const intl = createDatetimeFormatter(
+                dateFormat,
+                CHART_DATETIME_DEFAULTS,
+            );
             return (v) => intl.format(v);
         }
 
@@ -515,7 +512,7 @@ export abstract class AbstractChart implements ChartImplementation {
                 return undefined;
             }
 
-            const intl = createDateFormatter(dateFormat);
+            const intl = createDateFormatter(dateFormat, CHART_DATE_DEFAULTS);
             return (v) => intl.format(v);
         }
 
@@ -608,6 +605,11 @@ export abstract class AbstractChart implements ChartImplementation {
      * inputs in `uploadAndRender`; they take effect on next data load.
      */
     setPluginConfig(cfg: PluginConfig): void {
+        // Persistence echo vs. real change: a restore whose legend
+        // fields equal the current values (the round-trip of a
+        // completed drag) must not disturb legend scroll or an
+        // in-flight gesture; different values win and cancel any drag.
+        this._legend.reconcileConfig(this._pluginConfig, cfg);
         this._pluginConfig = { ...cfg };
         this._facetConfig = {
             ...this._facetConfig,

package/src/ts/charts/chart.ts

@@ -11,6 +11,7 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 import type { View } from "@perspective-dev/client";
+import { TILE_SOURCES } from "../map/tile-source";
 import type { ColumnDataMap } from "../data/view-reader";
 import type { WebGLContextManager } from "../webgl/context-manager";
 import type { ZoomController } from "../interaction/zoom-controller";
@@ -198,6 +199,8 @@ export interface ChartImplementation {
      */
     deselect?(): void;
 
+    repaintChrome?(): void;
+
     destroy(): void;
 }
 
@@ -431,13 +434,15 @@ export interface PluginConfig {
     gradient_color_mode: "mean" | "density" | "extreme" | "signed";
 
     /**
-     * Map basemap tile provider. Applies only to map plugin tags
-     * (`map-scatter`, `map-line`, `map-density`). Cartesian charts
-     * ignore the field. Surfaced as an enum on the settings panel so
-     * users can switch light/dark/voyager without writing custom
-     * tile-source code.
+     * Map basemap tile provider — a `TileSourceSpec` id from the
+     * tile-source registry ([map/tile-sources.json] entries plus any
+     * runtime `registerTileSource` additions). Applies only to map
+     * plugin tags (`map-scatter`, `map-line`, `map-density`); other
+     * charts ignore the field. The default is the JSON's FIRST entry
+     * (reordering the file changes the default), and unknown ids fall
+     * back to that same entry rather than blanking the map.
      */
-    map_tile_provider: "carto-positron" | "carto-dark-matter" | "carto-voyager";
+    map_tile_provider: string;
 
     /**
      * Map basemap alpha (0..1). Pre-multiplied into the tile fragment
@@ -446,8 +451,91 @@ export interface PluginConfig {
      * shows the tiles at full opacity.
      */
     map_tile_alpha: number;
+
+    /**
+     * Map plugins only. `true` (default): standard numeric axes in the
+     * usual cartesian gutters, with tick labels in degrees
+     * longitude/latitude (`122.4°W`) rather than Mercator meters.
+     * `false`: no axes, and the plot is full-bleed — the basemap fills
+     * the entire canvas, minus only the sidebar legend gutter when a
+     * legend is actually shown. Gridlines are never drawn in map mode
+     * — the gridline canvas composites BELOW the GL layer, so opaque
+     * basemap tiles would hide them.
+     */
+    numeric_axes: boolean;
+
+    /**
+     * Legend presentation mode. `"auto"` (default) resolves per frame
+     * to `"floating"` when every entry fits the default floating panel
+     * without scrolling (≤ 7 entries; continuous gradient legends
+     * always qualify) and to `"sidebar"` otherwise — see
+     * `resolveLegendMode`. Treemap overrides the default to
+     * `"sidebar"` (a floating panel over edge-to-edge tiles always
+     * occludes data).
+     */
+    legend_mode: "auto" | "sidebar" | "none" | "floating";
+
+    /**
+     * Floating-panel sizing regime. `"auto"` (default) sizes the panel
+     * to its CONTENT every frame — the height hugs the entry rows
+     * exactly, and the width hugs the widest entry label (measured on
+     * the chrome canvas). `"fixed"` uses the saved `legend_width_px` /
+     * `legend_height_px` verbatim.
+     *
+     * Applies to `legend_mode: "floating"` ONLY; the sidebar gutter is
+     * always `legend_width_px` (its height is the plot's). Dragging a
+     * resize handle switches an auto panel to `"fixed"` — otherwise
+     * the gesture would be undone by the next paint — and
+     * double-clicking a resize handle switches it back.
+     */
+    legend_size_mode: LegendSizeMode;
+
+    /**
+     * Legend width in CSS pixels. `0` (default) = automatic — each
+     * chart family keeps its historical gutter width (80–96px). In
+     * `"sidebar"` mode this is the full right-gutter width; in
+     * `"floating"` mode it is the panel width. Clamped at paint time
+     * to at most half the canvas width so a saved wide legend cannot
+     * crush a small panel. Ignored by a floating panel in
+     * `legend_size_mode: "auto"`.
+     */
+    legend_width_px: number;
+
+    /**
+     * Floating-legend panel height in CSS pixels. Ignored in
+     * `"sidebar"` mode (the legend spans the plot height) and by a
+     * floating panel in `legend_size_mode: "auto"`. Clamped at paint
+     * time to the canvas height.
+     */
+    legend_height_px: number;
+
+    /**
+     * Canvas corner that `legend_x` / `legend_y` are measured FROM.
+     * Floating mode only. The panel keeps its distance to this corner
+     * across panel resizes — anchor `"bottom-right"` with small
+     * offsets stays glued to the bottom-right.
+     */
+    legend_anchor: LegendAnchor;
+
+    legend_x: number;
+    legend_y: number;
+    legend_opacity: number;
+
+    /** Per-column width cap for tooltip grid cells, in CSS pixels. */
+    tooltip_max_column_px: number;
+
+    /** Tooltip background/border alpha (0..1). */
+    tooltip_opacity: number;
 }
 
+export type LegendAnchor =
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right";
+
+export type LegendSizeMode = "auto" | "fixed";
+
 export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
     auto_alt_y_axis: false,
     facet_mode: "grid",
@@ -465,6 +553,17 @@ export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
     gradient_intensity: 0.6,
     gradient_heat_max: 4.0,
     gradient_color_mode: "mean",
-    map_tile_provider: "carto-positron",
+    map_tile_provider: TILE_SOURCES.list()[0].id,
     map_tile_alpha: 1.0,
+    numeric_axes: true,
+    legend_mode: "auto",
+    legend_size_mode: "auto",
+    legend_width_px: 0,
+    legend_height_px: 160,
+    legend_anchor: "top-right",
+    legend_x: 0,
+    legend_y: 0,
+    legend_opacity: 0.8,
+    tooltip_max_column_px: 160,
+    tooltip_opacity: 0.8,
 };

package/src/ts/charts/common/draw-tooltip-box.ts

@@ -12,6 +12,13 @@
 
 import type { Context2D } from "../canvas-types";
 import type { Theme } from "../../theme/theme";
+import {
+    measureTooltipGrid,
+    paintTooltipGrid,
+    DEFAULT_TOOLTIP_STYLE,
+    type TooltipContent,
+    type TooltipStyle,
+} from "../../interaction/tooltip-grid";
 
 /**
  * Draw a freestanding tooltip box anchored near (cx, cy), measuring
@@ -22,32 +29,21 @@ import type { Theme } from "../../theme/theme";
 export function drawTooltipBox(
     ctx: Context2D,
     theme: Theme,
-    lines: string[],
+    grid: TooltipContent,
     cx: number,
     cy: number,
     cssWidth: number,
     cssHeight: number,
     fontFamily: string,
+    style: TooltipStyle = DEFAULT_TOOLTIP_STYLE,
 ): void {
-    if (lines.length === 0) {
+    if (grid.length === 0) {
         return;
     }
 
-    const { tooltipBg, tooltipText, tooltipBorder } = theme;
-
     ctx.font = `11px ${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, style.maxColumnPx);
+    const { boxW, boxH } = measured;
 
     let tx = cx + 12;
     let ty = cy - boxH - 8;
@@ -67,18 +63,5 @@ export function drawTooltipBox(
         ty = cssHeight - boxH - 4;
     }
 
-    ctx.fillStyle = tooltipBg;
-    ctx.strokeStyle = tooltipBorder;
-    ctx.lineWidth = 1;
-    ctx.beginPath();
-    ctx.roundRect(tx, ty, boxW, boxH, 4);
-    ctx.fill();
-    ctx.stroke();
-
-    ctx.fillStyle = 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);
-    }
+    paintTooltipGrid(ctx, measured, tx, ty, theme, style.opacity);
 }