@perspective-dev/viewer-charts 5.2.0 → 5.3.1

package/src/ts/plugin/plugin.ts

@@ -10,13 +10,19 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+import { colorsToCss, stopsToCss } from "../theme/gradient";
 import type { View } from "@perspective-dev/client";
 import type {
     HTMLPerspectiveViewerElement,
     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,
@@ -24,9 +30,19 @@ 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";
+import { resolvePalette } from "../theme/palette";
+import { vec3ToHexColor } from "../utils/css";
 
 /**
  * Facet-rendering defaults shared by every chart. Per-chart overrides
@@ -37,6 +53,26 @@ import { RENDER_BLIT_MODE } from "../config";
  */
 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
@@ -52,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();
@@ -394,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({
@@ -432,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,
@@ -449,23 +591,79 @@ export class HTMLPerspectiveViewerWebGLPluginElement
             priority: 0,
             can_render_column_styles:
                 !!this._chartType.default_chart_type ||
-                this._chartType.category === "Cartesian Charts",
+                this._chartType.category === "Cartesian Charts" ||
+                this._chartType.category === "Hierarchical Charts" ||
+                this._chartType.category === "Map Charts",
         };
     }
 
     column_config_schema(
         column_type: string,
-        _group: string | undefined,
-        _column_name: string,
+        group: string | undefined,
+        column_name: string,
         current_value: Record<string, unknown> | null,
-        _viewer_config?: { group_by?: string[]; group_rollup_mode?: string },
+        viewer_config?: {
+            columns?: (string | null)[];
+            group_by?: string[];
+            split_by?: string[];
+            group_rollup_mode?: string;
+        },
     ) {
         const fields: Array<Record<string, unknown> & { kind: string }> = [];
 
+        if (group === "Color") {
+            const numeric_gradient =
+                this._chartType.category === "Hierarchical Charts"
+                    ? column_type === "integer" ||
+                      column_type === "float" ||
+                      column_type === "date" ||
+                      column_type === "datetime"
+                    : column_type !== "string";
+            if (numeric_gradient) {
+                fields.push({
+                    kind: "GradientStops",
+                    key: "gradient",
+                    default: this._themeGradientStopsSpec(),
+                });
+            } else {
+                fields.push({
+                    kind: "Palette",
+                    key: "palette",
+                    default: this._themeSeriesPaletteHex(),
+                });
+            }
+        }
+
         // Y-series plugins expose the per-column chart_type picker; non-Y
         // plugins leave `default_chart_type` unset.
         const def = this._chartType.default_chart_type;
         if (def && (column_type === "integer" || column_type === "float")) {
+            const is_series_glyph =
+                def === "bar" ||
+                def === "line" ||
+                def === "scatter" ||
+                def === "area";
+
+            if (is_series_glyph) {
+                const has_split = (viewer_config?.split_by?.length ?? 0) > 0;
+                if (has_split) {
+                    fields.push({
+                        kind: "Palette",
+                        key: "palette",
+                        default: this._themeSeriesPaletteHex(),
+                    });
+                } else {
+                    const slot = (viewer_config?.columns ?? [])
+                        .filter((c): c is string => !!c)
+                        .indexOf(column_name);
+                    fields.push({
+                        kind: "Color",
+                        key: "color",
+                        default: this._themeSeriesColorHex(Math.max(0, slot)),
+                    });
+                }
+            }
+
             fields.push({
                 kind: "Enum",
                 key: "chart_type",
@@ -493,12 +691,6 @@ export class HTMLPerspectiveViewerWebGLPluginElement
                 });
             }
 
-            const is_series_glyph =
-                def === "bar" ||
-                def === "line" ||
-                def === "scatter" ||
-                def === "area";
-
             if (is_series_glyph) {
                 fields.push({
                     kind: "Bool",
@@ -537,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 };
@@ -550,11 +753,62 @@ 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);
+                }
+
+                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 {
+        return resolveThemeFromVars(snapshotThemeVars(this));
+    }
+
+    private static readonly GRADIENT_PALETTE_FALLBACK_COUNT = 6;
+
+    private _themeSeriesPaletteHex(): string {
+        const theme = this._resolvedTheme();
+        const count =
+            theme.seriesPalette.length ||
+            HTMLPerspectiveViewerWebGLPluginElement.GRADIENT_PALETTE_FALLBACK_COUNT;
+        return colorsToCss(
+            resolvePalette(theme.seriesPalette, theme.gradientStops, count),
         );
+    }
 
-        return { fields };
+    private _themeSeriesColorHex(idx: number): string {
+        const theme = this._resolvedTheme();
+        const count = Math.max(theme.seriesPalette.length, idx + 1);
+        return vec3ToHexColor(
+            resolvePalette(theme.seriesPalette, theme.gradientStops, count)[
+                idx
+            ],
+        );
+    }
+
+    private _themeGradientStopsSpec(): string {
+        return stopsToCss(this._resolvedTheme().gradientStops);
     }
 
     async draw(view: View): Promise<void> {

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) {