@perspective-dev/viewer-charts 5.3.0 → 5.4.0

package/src/ts/plugin/plugin.ts

@@ -17,7 +17,12 @@ import type {
     IPerspectiveViewerPlugin,
     PluginStaticConfig,
 } from "@perspective-dev/viewer";
-import { ChartTypeConfig, PluginConfigField } from "./charts";
+import {
+    ChartTypeConfig,
+    LEGEND_FIELDS,
+    TOOLTIP_FIELDS,
+    PluginConfigField,
+} from "./charts";
 import style from "../../css/perspective-viewer-charts.css";
 import {
     DEFAULT_FACET_CONFIG,
@@ -25,8 +30,14 @@ import {
     type FacetConfig,
     type PluginConfig,
 } from "../charts/chart";
+import {
+    CHART_DATE_DEFAULTS,
+    CHART_DATETIME_DEFAULTS,
+    CHART_NUMBER_DEFAULTS,
+} from "./format-defaults";
 import { RawEventForwarder } from "../interaction/raw-event-forwarder";
 import { RendererTransport } from "../transport/renderer-transport";
+import { TILE_SOURCES, type TileSourceSpec } from "../map/tile-source";
 import { RENDER_BLIT_MODE } from "../config";
 import { snapshotThemeVars } from "../theme/theme-snapshot";
 import { resolveThemeFromVars, type Theme } from "../theme/theme";
@@ -42,6 +53,26 @@ import { vec3ToHexColor } from "../utils/css";
  */
 const FACET_CONFIG_DEFAULTS: FacetConfig = { ...DEFAULT_FACET_CONFIG };
 
+/**
+ * Register a raster XYZ tile provider at runtime. The provider joins
+ * the bundled [map/tile-sources.json] entries in the settings panel's
+ * `map_tile_provider` enum and resolves on any map chart from its next
+ * config forward onward — the resolved spec rides every outgoing
+ * `setPluginConfig` / `init` message alongside the config that names
+ * it, so no separate registry-sync operation exists. Re-registering an
+ * id replaces it (a changed template drops cached tiles via the
+ * content-derived cache identity); a chart currently displaying that
+ * id picks the replacement up on its next `restore()`. Throws
+ * `TypeError` on a malformed spec. Returns the normalized spec.
+ *
+ * A key-gated provider is registered with the key embedded in its
+ * `template` — keys never enter `plugin_config`, so they never appear
+ * in `save()` output.
+ */
+export function registerTileSource(spec: unknown): TileSourceSpec {
+    return TILE_SOURCES.register(spec);
+}
+
 /**
  * Static UI-control spec per `plugin_config` field. Mirrors the shape
  * `column_config_schema` already returns (datagrid). The runtime default
@@ -57,72 +88,157 @@ type FieldSpec =
       }
     | { kind: "Number"; min: number; max: number; step?: number };
 
-const FIELD_SCHEMAS: Record<PluginConfigField, FieldSpec> = {
-    auto_alt_y_axis: { kind: "Bool" },
-    include_zero: { kind: "Bool" },
-    domain_mode: {
-        kind: "Enum",
-        variants: [
-            { value: "fit", label: "Fit" },
-            { value: "expand", label: "Expand" },
-        ],
-    },
-    facet_mode: {
-        kind: "Enum",
-        variants: [
-            { value: "grid", label: "Grid" },
-            { value: "overlay", label: "Overlay" },
-        ],
-    },
-    facet_zoom_mode: {
-        kind: "Enum",
-        variants: [
-            { value: "shared", label: "Shared" },
-            { value: "independent", label: "Independent" },
+/**
+ * A `FieldSpec` entry may be a thunk when its contents depend on
+ * runtime state — `map_tile_provider`'s variants come from the tile-
+ * source registry, which grows via `registerTileSource`, so the enum
+ * must be resolved per `plugin_config_schema()` call rather than at
+ * module init.
+ */
+const FIELD_SCHEMAS: Record<PluginConfigField, FieldSpec | (() => FieldSpec)> =
+    {
+        auto_alt_y_axis: { kind: "Bool" },
+        include_zero: { kind: "Bool" },
+        domain_mode: {
+            kind: "Enum",
+            variants: [
+                { value: "fit", label: "Fit" },
+                { value: "expand", label: "Expand" },
+            ],
+        },
+        facet_mode: {
+            kind: "Enum",
+            variants: [
+                { value: "grid", label: "Grid" },
+                { value: "overlay", label: "Overlay" },
+            ],
+        },
+        facet_zoom_mode: {
+            kind: "Enum",
+            variants: [
+                { value: "shared", label: "Shared" },
+                { value: "independent", label: "Independent" },
+            ],
+        },
+        series_zoom_mode: {
+            kind: "Enum",
+            variants: [
+                { value: "dynamic", label: "Dynamic" },
+                { value: "fixed", label: "Fixed" },
+            ],
+        },
+        line_width_px: { kind: "Number", min: 0.5, step: 0.5, max: 16 },
+        point_size_px: { kind: "Number", min: 1, max: 32 },
+        band_inner_frac: { kind: "Number", min: 0.1, max: 1, step: 0.01 },
+        bar_inner_pad: { kind: "Number", min: 0, max: 0.9, step: 0.01 },
+        wick_width_px: { kind: "Number", min: 0.5, step: 0.5, max: 8 },
+        ohlc_line_width_px: { kind: "Number", min: 0.5, step: 0.5, max: 8 },
+        gradient_radius_px: { kind: "Number", min: 2, step: 1, max: 256 },
+        gradient_intensity: { kind: "Number", min: 0.05, step: 0.05, max: 4 },
+        gradient_heat_max: { kind: "Number", min: 0.1, step: 0.1, max: 64 },
+        gradient_color_mode: {
+            kind: "Enum",
+            variants: [
+                { value: "mean", label: "Mean (density-weighted)" },
+                { value: "density", label: "Density only" },
+                { value: "extreme", label: "Extremes" },
+                { value: "signed", label: "Signed sum" },
+            ],
+        },
+        map_tile_provider: () => ({
+            kind: "Enum",
+            variants: TILE_SOURCES.list().map((s) => ({
+                value: s.id,
+                label: s.label,
+            })),
+        }),
+        map_tile_alpha: { kind: "Number", min: 0, max: 1, step: 0.05 },
+        numeric_axes: { kind: "Bool" },
+        legend_mode: {
+            kind: "Enum",
+            variants: [
+                { value: "auto", label: "Auto" },
+                { value: "sidebar", label: "Sidebar" },
+                { value: "none", label: "None" },
+                { value: "floating", label: "Floating" },
+            ],
+        },
+        legend_size_mode: {
+            kind: "Enum",
+            variants: [
+                { value: "auto", label: "Auto" },
+                { value: "fixed", label: "Fixed" },
+            ],
+        },
+        // 0 = auto (the chart family's historical gutter width).
+        legend_width_px: { kind: "Number", min: 0, max: 512, step: 1 },
+        legend_height_px: { kind: "Number", min: 48, max: 1024, step: 1 },
+        legend_anchor: {
+            kind: "Enum",
+            variants: [
+                { value: "top-right", label: "Top Right" },
+                { value: "top-left", label: "Top Left" },
+                { value: "bottom-right", label: "Bottom Right" },
+                { value: "bottom-left", label: "Bottom Left" },
+            ],
+        },
+        legend_x: { kind: "Number", min: 0, max: 1, step: 0.01 },
+        legend_y: { kind: "Number", min: 0, max: 1, step: 0.01 },
+        legend_opacity: { kind: "Number", min: 0, max: 1, step: 0.05 },
+        tooltip_max_column_px: { kind: "Number", min: 40, max: 512, step: 1 },
+        tooltip_opacity: { kind: "Number", min: 0, max: 1, step: 0.05 },
+    };
+
+function fieldSpec(
+    key: PluginConfigField,
+    defaults: PluginConfig,
+): Record<string, unknown> & { kind: string } {
+    const entry = FIELD_SCHEMAS[key];
+    const spec = typeof entry === "function" ? entry() : entry;
+    return { ...spec, key, default: defaults[key] };
+}
+
+const PLUGIN_FIELD_GROUPS: ReadonlyArray<{
+    key: string;
+    fields: readonly PluginConfigField[];
+}> = [
+    {
+        key: "axes",
+        fields: [
+            "auto_alt_y_axis",
+            "include_zero",
+            "domain_mode",
+            "numeric_axes",
         ],
     },
-    series_zoom_mode: {
-        kind: "Enum",
-        variants: [
-            { value: "dynamic", label: "Dynamic" },
-            { value: "fixed", label: "Fixed" },
-        ],
+    {
+        key: "facets",
+        fields: ["facet_mode", "facet_zoom_mode", "series_zoom_mode"],
     },
-    line_width_px: { kind: "Number", min: 0.5, step: 0.5, max: 16 },
-    point_size_px: { kind: "Number", min: 1, max: 32 },
-    band_inner_frac: { kind: "Number", min: 0.1, max: 1, step: 0.01 },
-    bar_inner_pad: { kind: "Number", min: 0, max: 0.9, step: 0.01 },
-    wick_width_px: { kind: "Number", min: 0.5, step: 0.5, max: 8 },
-    ohlc_line_width_px: { kind: "Number", min: 0.5, step: 0.5, max: 8 },
-    gradient_radius_px: { kind: "Number", min: 2, step: 1, max: 256 },
-    gradient_intensity: { kind: "Number", min: 0.05, step: 0.05, max: 4 },
-    gradient_heat_max: { kind: "Number", min: 0.1, step: 0.1, max: 64 },
-    gradient_color_mode: {
-        kind: "Enum",
-        variants: [
-            { value: "mean", label: "Mean (density-weighted)" },
-            { value: "density", label: "Density only" },
-            { value: "extreme", label: "Extremes" },
-            { value: "signed", label: "Signed sum" },
+    {
+        key: "glyph",
+        fields: [
+            "line_width_px",
+            "point_size_px",
+            "band_inner_frac",
+            "bar_inner_pad",
+            "wick_width_px",
+            "ohlc_line_width_px",
         ],
     },
-    map_tile_provider: {
-        kind: "Enum",
-        variants: [
-            { value: "carto-positron", label: "Light (Positron)" },
-            { value: "carto-dark-matter", label: "Dark Matter" },
-            { value: "carto-voyager", label: "Voyager" },
+    {
+        key: "density",
+        fields: [
+            "gradient_color_mode",
+            "gradient_radius_px",
+            "gradient_intensity",
+            "gradient_heat_max",
         ],
     },
-    map_tile_alpha: { kind: "Number", min: 0, max: 1, step: 0.05 },
-};
-
-function fieldSpec(
-    key: PluginConfigField,
-    defaults: PluginConfig,
-): Record<string, unknown> & { kind: string } {
-    return { ...FIELD_SCHEMAS[key], key, default: defaults[key] };
-}
+    { key: "basemap", fields: ["map_tile_provider", "map_tile_alpha"] },
+    { key: "legend", fields: LEGEND_FIELDS },
+    { key: "tooltip", fields: TOOLTIP_FIELDS },
+];
 
 const GLOBAL_STYLES = (() => {
     const sheet = new CSSStyleSheet();
@@ -399,6 +515,19 @@ export class HTMLPerspectiveViewerWebGLPluginElement
                     zoomControls.classList.toggle("visible", !isDefault);
                 }
             },
+            onPluginConfigDelta: (fields) => {
+                this._pluginConfig = { ...this._pluginConfig, ...fields };
+                const host = this
+                    .parentElement as HTMLPerspectiveViewerElement | null;
+                (
+                    host?.restore(
+                        { plugin_config: fields },
+                        panel ? { panel } : undefined,
+                    ) as Promise<void> | undefined
+                )?.catch((e: unknown) => {
+                    console.error("legend config persistence failed", e);
+                });
+            },
         });
 
         await transport.init({
@@ -437,6 +566,14 @@ export class HTMLPerspectiveViewerWebGLPluginElement
         BLIT_MODE = mode;
     }
 
+    static registerTileSource(spec: unknown): TileSourceSpec {
+        return registerTileSource(spec);
+    }
+
+    static tileSources(): readonly TileSourceSpec[] {
+        return TILE_SOURCES.list();
+    }
+
     get_static_config(): PluginStaticConfig {
         return {
             name: this._chartType.name,
@@ -592,9 +729,20 @@ export class HTMLPerspectiveViewerWebGLPluginElement
         // Per-column formatter widgets. Surfaced for every chart type so
         // axes / tooltips / legends honor the user's format choice.
         if (column_type === "integer" || column_type === "float") {
-            fields.push({ kind: "NumberFormat" });
-        } else if (column_type === "date" || column_type === "datetime") {
-            fields.push({ kind: "DatetimeFormat" });
+            fields.push({
+                kind: "NumberFormat",
+                default: CHART_NUMBER_DEFAULTS,
+            });
+        } else if (column_type === "datetime") {
+            fields.push({
+                kind: "DatetimeFormat",
+                default: CHART_DATETIME_DEFAULTS,
+            });
+        } else if (column_type === "date") {
+            fields.push({
+                kind: "DatetimeFormat",
+                default: CHART_DATE_DEFAULTS,
+            });
         }
 
         return { fields };
@@ -605,11 +753,32 @@ export class HTMLPerspectiveViewerWebGLPluginElement
         group_rollup_mode?: string;
     }) {
         const defaults = this._effectiveDefaults();
-        const fields = this._chartType.applicable_plugin_fields.map((key) =>
-            fieldSpec(key, defaults),
-        );
+        const applicable = this._chartType.applicable_plugin_fields;
+        const present = new Set(applicable);
+
+        const grouped = new Set<PluginConfigField>();
+        const groups: Array<Record<string, unknown> & { kind: string }> = [];
+        for (const group of PLUGIN_FIELD_GROUPS) {
+            const members = group.fields.filter((k) => present.has(k));
+            if (members.length >= 1) {
+                for (const k of members) {
+                    grouped.add(k);
+                }
 
-        return { fields };
+                groups.push({
+                    kind: "Group",
+                    key: group.key,
+                    fields: members.map((k) => fieldSpec(k, defaults)),
+                });
+            }
+        }
+
+        const fields: Array<Record<string, unknown> & { kind: string }> =
+            applicable
+                .filter((k) => !grouped.has(k))
+                .map((k) => fieldSpec(k, defaults));
+
+        return { fields: [...fields, ...groups] };
     }
 
     private _resolvedTheme(): Theme {

package/src/ts/shaders/line.vert.glsl

@@ -21,8 +21,11 @@
 // `a_color_start` / `a_color_end` carry the segment endpoints' raw
 // color values (numeric data value for gradient, dictionary index for
 // categorical). The gradient LUT is sampled using the same mapping the
-// scatter shader uses — `(v - cmin) / (cmax - cmin)` with sign-aware
-// handling for zero-crossing domains. The two endpoints' colors are
+// scatter shader uses — `u_color_range` arrives PRE-SHAPED by the host:
+// the symmetric sign-pivot range (`colorRangePivot`) for numeric
+// columns, so linear normalization matches the CPU `colorValueToT`
+// used by the legend / heatmap / tree charts; raw `[0, N-1]` extents
+// for categorical index domains. The two endpoints' colors are
 // averaged so the segment reads as a single chord in gradient space.
 attribute vec2 a_start;
 attribute vec2 a_end;

package/src/ts/shaders/scatter.vert.glsl

@@ -47,13 +47,6 @@ void main() {
 
     v_point_size = gl_PointSize;
 
-    // Color-t mapping. Linear across `[cmin, cmax]` for single-sign
-    // domains (which includes categorical `[0, N-1]` split / string
-    // indices, so the colors match `interpolatePalette`'s even sampling
-    // used by the legend). When the domain actually crosses zero we
-    // switch to sign-aware so the value 0 always lands at the 50% stop
-    // of the diverging gradient — matching heatmap and the Canvas2D
-    // tooltip paths.
     float cmin = u_color_range.x;
     float cmax = u_color_range.y;
     if(cmax <= cmin) {

package/src/ts/theme/gradient.ts

@@ -497,6 +497,30 @@ export function colorValueToT(
     return t < 0 ? 0 : t > 1 ? 1 : t;
 }
 
+export function colorRangePivot(
+    colorMin: number,
+    colorMax: number,
+): [number, number] {
+    if (!isFinite(colorMin) || !isFinite(colorMax) || colorMin >= colorMax) {
+        return [0, 0];
+    }
+
+    let denom: number;
+    if (colorMin >= 0) {
+        denom = colorMax;
+    } else if (colorMax <= 0) {
+        denom = -colorMin;
+    } else {
+        denom = Math.max(-colorMin, colorMax);
+    }
+
+    if (denom <= 0) {
+        return [0, 0];
+    }
+
+    return [-denom, denom];
+}
+
 /**
  * Convert a discrete series palette (from `--psp-charts--series-N--color`)
  * into a `GradientStop[]` with stops at `i / (N - 1)`. The resulting

package/src/ts/transport/protocol.ts

@@ -13,6 +13,7 @@
 import type { FacetConfig, PluginConfig } from "../charts/chart";
 import type { PerspectiveClickDetail } from "../event-detail";
 import type { ThemeSnapshot } from "../theme/theme";
+import type { TileSourceSpec } from "../map/tile-source";
 import type { ViewConfig } from "@perspective-dev/client";
 
 export type { ThemeSnapshot };
@@ -53,6 +54,7 @@ export type WorkerMsg =
     | SetCursorMsg
     | UserClickMsg
     | UserSelectMsg
+    | PluginConfigDeltaMsg
     | LoadAndRenderAckMsg
     | ResizeAckMsg
     | FrameBitmapMsg
@@ -185,6 +187,17 @@ export interface InitMsg {
     columnsConfig?: Record<string, any>;
     defaultChartType?: string;
 
+    /**
+     * Resolved spec for `pluginConfig.map_tile_provider`, when the
+     * plugin realm's registry knows the id — see
+     * {@link SetPluginConfigMsg.tileSource} for the invariant. Applied
+     * to the worker realm's registry before the chart impl is
+     * constructed. Bundled [map/tile-sources.json] entries ship inside
+     * the worker bundle, so this matters only for runtime-registered
+     * providers.
+     */
+    tileSource?: TileSourceSpec;
+
     /**
      * Pre-resolved CSS-variable theme snapshot from the host.
      */
@@ -271,6 +284,18 @@ export interface SetColumnsConfigMsg {
 export interface SetPluginConfigMsg {
     kind: "setPluginConfig";
     cfg: PluginConfig;
+
+    /**
+     * Resolved spec for `cfg.map_tile_provider`, when the plugin
+     * realm's registry knows the id. Riding the config keeps the two
+     * realms' registries convergent with NO eager mirroring: the
+     * worker registers this spec before applying `cfg`, so it can
+     * never hold a config whose provider it cannot resolve —
+     * regardless of when `registerTileSource` ran relative to
+     * renderer construction. Absent for unknown ids (the worker falls
+     * back to the default basemap).
+     */
+    tileSource?: TileSourceSpec;
 }
 
 export interface SetBufferMaxCapacityMsg {
@@ -317,6 +342,7 @@ export interface LoadAndRenderMsg {
 export interface LoadAndRenderAckMsg {
     kind: "loadAndRenderAck";
     msgId: number;
+    error?: string;
 }
 
 export interface RedrawMsg {
@@ -417,7 +443,8 @@ export interface SnapshotPngReqMsg {
 export interface SnapshotPngReplyMsg {
     kind: "snapshotPngReply";
     requestId: number;
-    blob: Blob;
+    blob?: Blob;
+    error?: string;
 }
 
 export interface DestroyMsg {
@@ -481,7 +508,9 @@ export interface ErrorMsg {
  */
 export interface PinTooltipMsg {
     kind: "pinTooltip";
-    lines: string[];
+
+    grid: string[][];
+    style: { opacity: number; maxColumnPx: number };
     pos: { px: number; py: number };
     bounds: { cssWidth: number; cssHeight: number };
 }
@@ -501,6 +530,21 @@ export interface SetCursorMsg {
     cursor: string;
 }
 
+/**
+ * Renderer → host: a completed legend gesture (sidebar width drag,
+ * floating move / resize) produced new values for the legend's
+ * `plugin_config` fields. Posted ONCE per gesture, at pointerup — never
+ * per pointermove — with only the fields the gesture changed. The host
+ * plugin persists them through the viewer's public `restore` surface
+ * (a user-gesture echo), which merges the host bucket, refreshes the
+ * settings form, and echoes one `setPluginConfig` back with the same
+ * values (a no-op by the worker's legend-field equality guard).
+ */
+export interface PluginConfigDeltaMsg {
+    kind: "pluginConfigDelta";
+    fields: Record<string, string | number | boolean>;
+}
+
 /**
  * Renderer → host: a user click landed on a chart glyph. Host
  * re-dispatches as `CustomEvent<PerspectiveClickDetail>` on the