@perspective-dev/viewer-charts 5.1.0 → 5.3.0

package/src/ts/charts/series/series-type.ts

@@ -10,6 +10,8 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+import { parseCssColorList, parseCssColorStrict } from "../../theme/gradient";
+
 export type ChartType = "bar" | "line" | "scatter" | "area";
 
 /**
@@ -45,6 +47,18 @@ export interface ColumnChartConfig {
      * `"skip"`). Default `"skip"`. No effect on bar / scatter.
      */
     interpolate?: InterpolateMode;
+
+    /**
+     * Single series-color override (`#rrggbb`) — the no-`split_by`
+     * shape.
+     */
+    color?: string;
+
+    /**
+     * Discrete color palette cycled over this column's split-generated
+     * series — the `split_by` shape.
+     */
+    palette?: string;
 }
 
 /**
@@ -98,6 +112,57 @@ export function resolveAltAxis(
     return cfg?.[aggName]?.alt_axis === true;
 }
 
+/**
+ * Resolve a per-series color override from `columns_config`, or `null`
+ * when the theme palette applies.
+ */
+export function resolveSeriesColorOverride(
+    series: { aggName: string; splitIdx: number },
+    facetActive: boolean,
+    cfg: Record<string, ColumnChartConfig> | undefined,
+): [number, number, number] | null {
+    const entry = cfg?.[series.aggName];
+    if (!entry) {
+        return null;
+    }
+
+    const palette =
+        typeof entry.palette === "string"
+            ? parsePaletteCached(entry.palette)
+            : null;
+    if (palette && palette.length > 0) {
+        const idx = facetActive ? 0 : series.splitIdx % palette.length;
+        return palette[idx];
+    }
+
+    if (typeof entry.color === "string") {
+        return parseCssColorStrict(entry.color) ?? null;
+    }
+
+    return null;
+}
+
+const PALETTE_PARSE_CACHE = new Map<
+    string,
+    Array<[number, number, number]> | null
+>();
+
+function parsePaletteCached(
+    src: string,
+): Array<[number, number, number]> | null {
+    let parsed = PALETTE_PARSE_CACHE.get(src);
+    if (parsed === undefined) {
+        parsed = parseCssColorList(src);
+        if (PALETTE_PARSE_CACHE.size > 256) {
+            PALETTE_PARSE_CACHE.clear();
+        }
+
+        PALETTE_PARSE_CACHE.set(src, parsed);
+    }
+
+    return parsed;
+}
+
 /**
  * Resolve the interpolation mode for this aggregate.
  */

package/src/ts/charts/series/series.ts

@@ -41,6 +41,7 @@ import {
     showBarPinnedTooltipForSample,
 } from "./series-interact";
 import { resolvePalette } from "../../theme/palette";
+import { resolveSeriesColorOverride } from "./series-type";
 import { LineGlyph } from "./glyphs/draw-lines";
 import { ScatterGlyph } from "./glyphs/draw-scatter";
 import { AreaGlyph } from "./glyphs/draw-areas";
@@ -250,13 +251,16 @@ export class SeriesChart extends CategoricalYChart {
     /**
      * Cached palette + identity-keys for short-circuiting per-frame
      * resolution. Inputs (`seriesPalette` ref, `gradientStops` ref,
-     * `series.length`) only change on data load or `restyle()`.
+     * `series.length`, `_columnsConfig` ref — per-series color
+     * overrides) only change on data load, `restyle()`, or
+     * `setColumnsConfig`.
      */
     _paletteCache: [number, number, number][] | null = null;
     _paletteCacheKey: {
         seriesPalette: [number, number, number][] | null;
         gradientStops: unknown;
         seriesLength: number;
+        columnsConfig: unknown;
     } | null = null;
 
     /**
@@ -514,9 +518,10 @@ export class SeriesChart extends CategoricalYChart {
             return;
         }
 
-        const groupByValues: (string | null)[] = this._rowPaths.map(
-            (level) => level.labels[b.catIdx] ?? null,
-        );
+        const groupByValues: (string | number | null)[] =
+            this._categoryAxisMode === "numeric" && this._categoryPositions
+                ? [this._categoryPositions[b.catIdx] ?? null]
+                : this._rowPaths.map((level) => level.labels[b.catIdx] ?? null);
         const splitKey = this._splitPrefixes[b.splitIdx] ?? "";
         const splitByValues =
             this._splitBy.length > 0 && splitKey !== ""
@@ -903,6 +908,7 @@ export function ensurePalette(chart: SeriesChart): boolean {
     const theme = chart._resolveTheme();
     const seriesPalette = theme.seriesPalette;
     const gradientStops = theme.gradientStops;
+    const columnsConfig = chart._columnsConfig;
     const paletteCount = chart._facetActive
         ? Math.max(1, chart._aggregates.length)
         : chart._series.length;
@@ -913,7 +919,8 @@ export function ensurePalette(chart: SeriesChart): boolean {
         key &&
         key.seriesPalette === seriesPalette &&
         key.gradientStops === gradientStops &&
-        key.seriesLength === paletteCount
+        key.seriesLength === paletteCount &&
+        key.columnsConfig === columnsConfig
     ) {
         return false;
     }
@@ -928,12 +935,18 @@ export function ensurePalette(chart: SeriesChart): boolean {
         seriesPalette,
         gradientStops,
         seriesLength: paletteCount,
+        columnsConfig,
     };
 
     for (let i = 0; i < chart._series.length; i++) {
-        chart._series[i].color = chart._facetActive
-            ? palette[chart._series[i].aggIdx]
-            : palette[i];
+        const series = chart._series[i];
+        const themed = chart._facetActive ? palette[series.aggIdx] : palette[i];
+        series.color =
+            resolveSeriesColorOverride(
+                series,
+                chart._facetActive,
+                columnsConfig,
+            ) ?? themed;
     }
 
     return true;

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

@@ -501,7 +501,16 @@ function drawArcs(
 
 //  Chrome overlay (Canvas2D)
 
+/**
+ * Render the chrome overlay (labels, center text, hover highlight +
+ * tooltip).
+ */
 export function renderSunburstChromeOverlay(chart: SunburstChart): void {
+    paintSunburstChromeOverlay(chart);
+    chart.presentOverlay();
+}
+
+function paintSunburstChromeOverlay(chart: SunburstChart): void {
     if (!chart._chromeCanvas || chart._currentRootId === NULL_NODE) {
         return;
     }

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

@@ -467,6 +467,11 @@ function emitRect(
  * tooltip + highlight on top.
  */
 export function renderTreemapChromeOverlay(chart: TreemapChart): void {
+    paintTreemapChromeOverlay(chart);
+    chart.presentOverlay();
+}
+
+function paintTreemapChromeOverlay(chart: TreemapChart): void {
     if (!chart._chromeCanvas || chart._currentRootId === NULL_NODE) {
         return;
     }

package/src/ts/layout/ticks.ts

@@ -111,6 +111,30 @@ export function formatTickValue(val: number): string {
     return val.toFixed(2);
 }
 
+/**
+ * Cached `Intl.DateTimeFormat` per option shape. `Date.prototype.
+ * toLocale*` constructs a fresh `DateTimeFormat` (plus its ICU
+ * backing) on EVERY call — ~30µs each — which turned per-row label
+ * synthesis over large pivots into a multi-second stall. A cached
+ * formatter's `format()` is ~1µs. Keyed by precision tier; the
+ * default locale is fixed for the lifetime of the worker, so entries
+ * never invalidate.
+ */
+const DATE_FORMAT_CACHE = new Map<string, Intl.DateTimeFormat>();
+
+function cachedDateFormat(
+    key: string,
+    options: Intl.DateTimeFormatOptions,
+): Intl.DateTimeFormat {
+    let fmt = DATE_FORMAT_CACHE.get(key);
+    if (!fmt) {
+        fmt = new Intl.DateTimeFormat(undefined, options);
+        DATE_FORMAT_CACHE.set(key, fmt);
+    }
+
+    return fmt;
+}
+
 /**
  * Format a timestamp (ms since epoch) as a human-readable date/time label.
  * Adapts precision based on the tick spacing.
@@ -129,49 +153,49 @@ export function formatDateTickValue(val: number, stepMs?: number): string {
 
         if (stepMs >= DAY * 28) {
             // Monthly or longer — show year-month
-            return d.toLocaleDateString(undefined, {
+            return cachedDateFormat("ym", {
                 year: "numeric",
                 month: "short",
-            });
+            }).format(d);
         }
 
         if (stepMs >= DAY) {
             // Daily — show month and day
-            return d.toLocaleDateString(undefined, {
+            return cachedDateFormat("md", {
                 month: "short",
                 day: "numeric",
-            });
+            }).format(d);
         }
 
         if (stepMs >= HOUR) {
             // Hourly
-            return d.toLocaleString(undefined, {
+            return cachedDateFormat("mdh", {
                 month: "short",
                 day: "numeric",
                 hour: "numeric",
-            });
+            }).format(d);
         }
 
         if (stepMs >= MINUTE) {
             // Minutes
-            return d.toLocaleTimeString(undefined, {
+            return cachedDateFormat("hm", {
                 hour: "numeric",
                 minute: "2-digit",
-            });
+            }).format(d);
         }
 
         // Sub-minute
-        return d.toLocaleTimeString(undefined, {
+        return cachedDateFormat("hms", {
             hour: "numeric",
             minute: "2-digit",
             second: "2-digit",
-        });
+        }).format(d);
     }
 
     // Default: show date only
-    return d.toLocaleDateString(undefined, {
+    return cachedDateFormat("ymd", {
         year: "numeric",
         month: "short",
         day: "numeric",
-    });
+    }).format(d);
 }

package/src/ts/plugin/charts.ts

@@ -44,6 +44,33 @@ export interface ChartTypeConfig {
      */
     applicable_plugin_fields: readonly PluginConfigField[];
 
+    /**
+     * What `group_by` DRAWS in this chart, e.g. `"X Axis"` for the
+     * Y-series charts. Omitted where the field has no visual role of
+     * its own and is a plain aggregation key — the X/Y and map charts,
+     * whose axes both come from `columns`.
+     *
+     * The `group_by` counterpart of `initial.names`: one declaration
+     * says what every view field draws, so the settings UI's labels and
+     * the agent's `list_plugins` contract read the same source instead
+     * of restating the mapping.
+     */
+    group_by_role?: string;
+
+    /** What `split_by` DRAWS in this chart. See {@link group_by_role}. */
+    split_by_role?: string;
+
+    /**
+     * Set on the charts that CONNECT their points in row order, so the
+     * view's row order shows up in the drawing: without a `sort` the
+     * line follows the table's natural order, which reads as a tangle
+     * unless the rows already arrive ordered along the X axis. The point
+     * charts (scatter, density) are unaffected, and a pre-ordered table
+     * needs no `sort` — which is why this is declared per chart rather
+     * than inferred from an empty `sort`.
+     */
+    connects_row_order?: boolean;
+
     /**
      * Per-chart-type overrides for `DEFAULT_PLUGIN_CONFIG`. Used when a
      * field's sensible default differs by chart family — currently
@@ -187,6 +214,9 @@ function make(
             | "max_columns"
             | "default_chart_type"
             | "plugin_field_defaults"
+            | "group_by_role"
+            | "split_by_role"
+            | "connects_row_order"
         >
     >,
 ): ChartTypeConfig {
@@ -205,30 +235,52 @@ function make(
         ...(overrides?.plugin_field_defaults
             ? { plugin_field_defaults: overrides.plugin_field_defaults }
             : {}),
+        ...(overrides?.group_by_role
+            ? { group_by_role: overrides.group_by_role }
+            : {}),
+        ...(overrides?.split_by_role
+            ? { split_by_role: overrides.split_by_role }
+            : {}),
+        ...(overrides?.connects_row_order
+            ? { connects_row_order: overrides.connects_row_order }
+            : {}),
     };
 }
 
 const FIN_NAMES = ["Open", "Close", "High", "Low", "Tooltip"];
 const HIER_NAMES = ["Size", "Color", "Tooltip"];
 
+const SERIES_Y_ROLES = { group_by_role: "X Axis", split_by_role: "Series" };
+const SERIES_X_ROLES = { group_by_role: "Y Axis", split_by_role: "Series" };
+const CART_ROLES = {};
+const HIER_ROLES = { group_by_role: "Hierarchy", split_by_role: "Facets" };
+const HEATMAP_ROLES = { group_by_role: "X Axis", split_by_role: "Y Axis" };
+const FIN_ROLES = { group_by_role: "X Axis", split_by_role: "Series" };
+const MAP_ROLES = {};
+
 const CHARTS: ChartTypeConfig[] = [
     make("X Bar", "x-bar", SERIES, SELECT, 1, X_AXIS, SERIES_FIELDS, {
+        ...SERIES_X_ROLES,
         default_chart_type: "bar",
         plugin_field_defaults: ZERO_ANCHORED_DEFAULTS,
     }),
     make("Y Bar", "y-bar", SERIES, SELECT, 1, Y_AXIS, SERIES_FIELDS, {
+        ...SERIES_Y_ROLES,
         default_chart_type: "bar",
         plugin_field_defaults: ZERO_ANCHORED_DEFAULTS,
     }),
     make("Y Line", "y-line", SERIES, SELECT, 1, Y_AXIS, SERIES_FIELDS, {
+        ...SERIES_Y_ROLES,
         default_chart_type: "line",
         plugin_field_defaults: SERIES_DEFAULTS,
     }),
     make("Y Scatter", "y-scatter", SERIES, SELECT, 1, Y_AXIS, SERIES_FIELDS, {
+        ...SERIES_Y_ROLES,
         default_chart_type: "scatter",
         plugin_field_defaults: SERIES_DEFAULTS,
     }),
     make("Y Area", "y-area", SERIES, SELECT, 1, Y_AXIS, SERIES_FIELDS, {
+        ...SERIES_Y_ROLES,
         default_chart_type: "area",
         plugin_field_defaults: ZERO_ANCHORED_DEFAULTS,
     }),
@@ -240,6 +292,7 @@ const CHARTS: ChartTypeConfig[] = [
         2,
         ["X Axis", "Y Axis", "Color", "Size", "Label", "Tooltip"],
         CARTESIAN_FIELDS,
+        { ...CART_ROLES },
     ),
     make(
         "X/Y Line",
@@ -249,6 +302,7 @@ const CHARTS: ChartTypeConfig[] = [
         2,
         ["X Axis", "Y Axis", "Tooltip"],
         CARTESIAN_FIELDS,
+        { ...CART_ROLES, connects_row_order: true },
     ),
     make(
         "Density",
@@ -258,15 +312,24 @@ const CHARTS: ChartTypeConfig[] = [
         2,
         ["X Axis", "Y Axis", "Color", "Tooltip"],
         DENSITY_FIELDS,
+        { ...CART_ROLES },
     ),
-    make("Treemap", "treemap", HIER, TOGGLE, 1, HIER_NAMES, NO_FIELDS),
-    make("Sunburst", "sunburst", HIER, TOGGLE, 1, HIER_NAMES, NO_FIELDS),
-    make("Heatmap", "heatmap", HIER, SELECT, 1, ["Color"], HEATMAP_FIELDS),
+    make("Treemap", "treemap", HIER, TOGGLE, 1, HIER_NAMES, NO_FIELDS, {
+        ...HIER_ROLES,
+    }),
+    make("Sunburst", "sunburst", HIER, TOGGLE, 1, HIER_NAMES, NO_FIELDS, {
+        ...HIER_ROLES,
+    }),
+    make("Heatmap", "heatmap", HIER, SELECT, 1, ["Color"], HEATMAP_FIELDS, {
+        ...HEATMAP_ROLES,
+    }),
     make("Candlestick", "candlestick", FIN, TOGGLE, 1, FIN_NAMES, FIN_FIELDS, {
+        ...FIN_ROLES,
         default_chart_type: "candlestick",
         plugin_field_defaults: SERIES_DEFAULTS,
     }),
     make("OHLC", "ohlc", FIN, TOGGLE, 1, FIN_NAMES, FIN_FIELDS, {
+        ...FIN_ROLES,
         default_chart_type: "ohlc",
         plugin_field_defaults: SERIES_DEFAULTS,
     }),
@@ -278,6 +341,7 @@ const CHARTS: ChartTypeConfig[] = [
         2,
         ["Longitude", "Latitude", "Color", "Size", "Label", "Tooltip"],
         MAP_SCATTER_FIELDS,
+        { ...MAP_ROLES },
     ),
     make(
         "Map Line",
@@ -287,6 +351,7 @@ const CHARTS: ChartTypeConfig[] = [
         2,
         ["Longitude", "Latitude", "Tooltip"],
         MAP_LINE_FIELDS,
+        { ...MAP_ROLES, connects_row_order: true },
     ),
     make(
         "Map Density",
@@ -296,6 +361,7 @@ const CHARTS: ChartTypeConfig[] = [
         2,
         ["Longitude", "Latitude", "Color", "Tooltip"],
         MAP_DENSITY_FIELDS,
+        { ...MAP_ROLES },
     ),
 ];
 

package/src/ts/plugin/plugin.ts

@@ -10,6 +10,7 @@
 // ┃ 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,
@@ -27,6 +28,10 @@ import {
 import { RawEventForwarder } from "../interaction/raw-event-forwarder";
 import { RendererTransport } from "../transport/renderer-transport";
 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
@@ -442,26 +447,86 @@ export class HTMLPerspectiveViewerWebGLPluginElement
             max_cells: this._chartType.max_cells,
             max_columns: this._chartType.max_columns,
             group_rollup_modes: ["flat"],
+            split_rollup_modes: ["flat"],
+            group_by_role: this._chartType.group_by_role,
+            split_by_role: this._chartType.split_by_role,
+            connects_row_order: !!this._chartType.connects_row_order,
             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",
@@ -489,12 +554,6 @@ export class HTMLPerspectiveViewerWebGLPluginElement
                 });
             }
 
-            const is_series_glyph =
-                def === "bar" ||
-                def === "line" ||
-                def === "scatter" ||
-                def === "area";
-
             if (is_series_glyph) {
                 fields.push({
                     kind: "Bool",
@@ -553,6 +612,36 @@ export class HTMLPerspectiveViewerWebGLPluginElement
         return { fields };
     }
 
+    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),
+        );
+    }
+
+    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> {
         // `draw` always indicates a view-level change (pivots, columns,
         // filters, sorts, schema, …) — invalidate the `domain_mode: