@perspective-dev/viewer-charts 5.2.0 → 5.3.1

package/dist/esm/plugin/charts.d.ts

@@ -63,5 +63,7 @@ export interface ChartTypeConfig {
      */
     plugin_field_defaults?: Partial<PluginConfig>;
 }
+export declare const LEGEND_FIELDS: readonly PluginConfigField[];
+export declare const TOOLTIP_FIELDS: readonly PluginConfigField[];
 declare const CHARTS: ChartTypeConfig[];
 export default CHARTS;

package/dist/esm/plugin/format-defaults.d.ts

@@ -0,0 +1,9 @@
+import type { DateFormatConfig, NumberFormatConfig } from "@perspective-dev/viewer/src/ts/column-format.js";
+/**
+ * The chart plugin's default per-column formats, declared to the viewer in
+ * `column_config_schema()` and applied by the render path under sparse or
+ * absent configs.
+ */
+export declare const CHART_NUMBER_DEFAULTS: NumberFormatConfig;
+export declare const CHART_DATETIME_DEFAULTS: DateFormatConfig;
+export declare const CHART_DATE_DEFAULTS: DateFormatConfig;

package/dist/esm/plugin/plugin.d.ts

@@ -1,6 +1,24 @@
 import type { View } from "@perspective-dev/client";
 import type { IPerspectiveViewerPlugin, PluginStaticConfig } from "@perspective-dev/viewer";
 import { ChartTypeConfig } from "./charts";
+import { type TileSourceSpec } from "../map/tile-source";
+/**
+ * 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 declare function registerTileSource(spec: unknown): TileSourceSpec;
 export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement implements IPerspectiveViewerPlugin {
     _chartType: ChartTypeConfig;
     private _initialized;
@@ -86,9 +104,13 @@ export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement
      *   contexts ([webgl/context-pool.ts]), so a page can exceed the cap.
      */
     static setBlitMode(mode: "direct" | "blit"): void;
+    static registerTileSource(spec: unknown): TileSourceSpec;
+    static tileSources(): readonly TileSourceSpec[];
     get_static_config(): PluginStaticConfig;
-    column_config_schema(column_type: string, _group: string | undefined, _column_name: string, current_value: Record<string, unknown> | null, _viewer_config?: {
+    column_config_schema(column_type: string, group: string | undefined, column_name: string, current_value: Record<string, unknown> | null, viewer_config?: {
+        columns?: (string | null)[];
         group_by?: string[];
+        split_by?: string[];
         group_rollup_mode?: string;
     }): {
         fields: (Record<string, unknown> & {
@@ -103,6 +125,11 @@ export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement
             kind: string;
         })[];
     };
+    private _resolvedTheme;
+    private static readonly GRADIENT_PALETTE_FALLBACK_COUNT;
+    private _themeSeriesPaletteHex;
+    private _themeSeriesColorHex;
+    private _themeGradientStopsSpec;
     draw(view: View): Promise<void>;
     update(view: View): Promise<void>;
     /**

package/dist/esm/theme/gradient.d.ts

@@ -15,6 +15,37 @@ export interface GradientStop {
  * that never set the gradient still produce sane output.
  */
 export declare function parseCssGradient(src: string | null | undefined): GradientStop[];
+/**
+ * A color literal — `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` or
+ * `rgba()` — as a `[0, 1]` RGB triple, or `null` for anything else.
+ */
+export declare function parseCssColorStrict(src: string): [number, number, number] | null;
+/**
+ * The shared `linear-gradient(...)` tokenizer of the viewer's CSS-valued
+ * config grammar.
+ */
+export declare function tokenizeLinearGradient(src: string): Array<[[number, number, number], number | null]> | null;
+/**
+ * Strict gradient reader: a `linear-gradient(...)` with ≥ 2 stops,
+ * positions optional, offsets clamped to `[0, 1]` and sorted, or `null`
+ * on malformed input.
+ */
+export declare function parseCssGradientStrict(src: string): GradientStop[] | null;
+/**
+ * Strict palette reader: a `linear-gradient(...)` of ≥ 1 colors with no
+ * positions, or `null` on malformed input.
+ */
+export declare function parseCssColorList(src: string): Array<[number, number, number]> | null;
+/**
+ * The viewer's canonical gradient string for `stops`: `linear-gradient(to
+ * right, #rrggbb P%, …)`, sorted, positions at 0.1% resolution.
+ */
+export declare function stopsToCss(stops: GradientStop[]): string;
+/**
+ * The viewer's canonical palette string for `colors`: the same frame
+ * with bare `#rrggbb` entries and no positions.
+ */
+export declare function colorsToCss(colors: Array<[number, number, number]>): string;
 /**
  * Piecewise-linear color sample at `t ∈ [0, 1]`. Returns RGBA in [0, 1].
  * Clamps `t` to the gradient's first/last stop outside `[0, 1]`.
@@ -29,6 +60,7 @@ export declare function sampleGradient(stops: GradientStop[], t: number): [numbe
  *   - degenerate   → 0.5 (single colour at the midpoint).
  */
 export declare function colorValueToT(value: number, colorMin: number, colorMax: number): number;
+export declare function colorRangePivot(colorMin: number, colorMax: number): [number, number];
 /**
  * Convert a discrete series palette (from `--psp-charts--series-N--color`)
  * into a `GradientStop[]` with stops at `i / (N - 1)`. The resulting

package/dist/esm/theme/overrides.d.ts

@@ -0,0 +1,19 @@
+import { type GradientStop } from "./gradient";
+import type { Theme } from "./theme";
+import type { Vec3 } from "./palette";
+/**
+ * Per-column color-scale overrides from the viewer's `columns_config`,
+ * patched into the resolved `Theme`'s `seriesPalette` / `gradientStops`
+ * fields.
+ */
+export declare function applyColumnColorOverrides(theme: Theme, columnsConfig: Record<string, any> | undefined, colorColumn: string | null): Theme;
+/**
+ * Parse a stored `palette` value into the `seriesPalette` shape, or
+ * `null` on anything malformed.
+ */
+export declare function parsePaletteOverride(raw: unknown): Vec3[] | null;
+/**
+ * Parse a stored `gradient` value into sorted `GradientStop[]`, or
+ * `null` on malformed input or fewer than 2 stops.
+ */
+export declare function parseGradientOverride(raw: unknown): GradientStop[] | null;

package/dist/esm/transport/protocol.d.ts

@@ -1,6 +1,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 };
 /**
@@ -10,7 +11,7 @@ export type { ThemeSnapshot };
  * chart's own renderer control plane.
  */
 export type ControlMsg = InitMsg | SetViewByNameMsg | SetColumnsConfigMsg | SetPluginConfigMsg | SetBufferMaxCapacityMsg | LoadAndRenderMsg | RedrawMsg | DeselectMsg | ResizeMsg | ClearMsg | InvalidateThemeMsg | RestoreZoomMsg | ResetAllZoomsMsg | ResetExpandedDomainMsg | SaveZoomReqMsg | SnapshotPngReqMsg | InteractionMsg | DestroyMsg;
-export type WorkerMsg = ReadyMsg | ZoomChangedMsg | SaveZoomReplyMsg | SnapshotPngReplyMsg | PinTooltipMsg | DismissTooltipMsg | SetCursorMsg | UserClickMsg | UserSelectMsg | LoadAndRenderAckMsg | ResizeAckMsg | FrameBitmapMsg | ErrorMsg;
+export type WorkerMsg = ReadyMsg | ZoomChangedMsg | SaveZoomReplyMsg | SnapshotPngReplyMsg | PinTooltipMsg | DismissTooltipMsg | SetCursorMsg | UserClickMsg | UserSelectMsg | PluginConfigDeltaMsg | LoadAndRenderAckMsg | ResizeAckMsg | FrameBitmapMsg | ErrorMsg;
 /**
  * Session-tagged envelopes for the shared-worker transport. Every
  * message between the host and the shared `Worker` carries a numeric
@@ -49,8 +50,19 @@ export interface InitMsg {
      * `dpr` and there is no host-side GL drawing buffer.
      */
     glCanvas?: OffscreenCanvas;
-    gridlinesCanvas: OffscreenCanvas;
-    chromeCanvas: OffscreenCanvas;
+    /**
+     * The gridlines (bottom) and chrome/axes (top) 2D layers.
+     * Transferred via `transferControlToOffscreen` on the host, present
+     * iff `renderMode === "direct"` — their pixels reach the screen
+     * through the compositor. In blit mode the renderer allocates
+     * worker-local surfaces instead and composites both layers into the
+     * shipped `FrameBitmapMsg`, so every layer of the frame rides the
+     * host's staged-present hold (a transferred canvas presents on the
+     * compositor's own schedule, unsynchronized with the host's layout
+     * commits — the one-frame axes warp on anticipated resizes).
+     */
+    gridlinesCanvas?: OffscreenCanvas;
+    chromeCanvas?: OffscreenCanvas;
     /**
      * `MessagePort` to the host's `ProxySession`. Worker mode only —
      * the worker bootstraps a fresh `Client` and bridges it through
@@ -113,6 +125,16 @@ 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.
      */
@@ -191,6 +213,17 @@ 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 {
     kind: "setBufferMaxCapacity";
@@ -234,6 +267,7 @@ export interface LoadAndRenderMsg {
 export interface LoadAndRenderAckMsg {
     kind: "loadAndRenderAck";
     msgId: number;
+    error?: string;
 }
 export interface RedrawMsg {
     kind: "redraw";
@@ -321,7 +355,8 @@ export interface SnapshotPngReqMsg {
 export interface SnapshotPngReplyMsg {
     kind: "snapshotPngReply";
     requestId: number;
-    blob: Blob;
+    blob?: Blob;
+    error?: string;
 }
 export interface DestroyMsg {
     kind: "destroy";
@@ -396,7 +431,11 @@ export interface ErrorMsg {
  */
 export interface PinTooltipMsg {
     kind: "pinTooltip";
-    lines: string[];
+    grid: string[][];
+    style: {
+        opacity: number;
+        maxColumnPx: number;
+    };
     pos: {
         px: number;
         py: number;
@@ -419,6 +458,20 @@ export interface SetCursorMsg {
     kind: "setCursor";
     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

package/dist/esm/transport/renderer-transport.d.ts

@@ -58,6 +58,7 @@ export declare class RendererTransport {
     private _pending;
     private _pendingCounter;
     private _onZoomChanged;
+    private _onPluginConfigDelta;
     /**
      * Cached zoom-default flag pushed by the renderer after each zoom
      * mutation. Surfaced sync via `allZoomsDefault()`; updates between
@@ -126,6 +127,7 @@ export declare class RendererTransport {
         maxCells: number;
         precompileShaders?: boolean;
         onZoomChanged?: (isDefault: boolean) => void;
+        onPluginConfigDelta?: (fields: Record<string, string | number | boolean>) => void;
     });
     init(opts: {
         gl: HTMLCanvasElement;
@@ -245,6 +247,7 @@ export declare class RendererTransport {
      * worth catching at the worker side.
      */
     private _resolvePending;
+    private _rejectPending;
     /**
      * Blit-mode handler: draw a renderer-emitted frame into the
      * visible 2D-context display canvas, then close the bitmap so its

package/dist/esm/utils/css.d.ts

@@ -1 +1,5 @@
 export declare function parseCSSColorToVec3(colorStr: string): [number, number, number];
+/**
+ * Format a `[0, 1]`-range RGB triple as a plain `#rrggbb` string.
+ */
+export declare function vec3ToHexColor(c: [number, number, number]): string;

package/dist/esm/worker/renderer.worker.d.ts

@@ -1,9 +1,10 @@
 import "./boot";
 import type { Client, Table, View } from "@perspective-dev/client";
 import { WebGLContextManager } from "../webgl/context-manager";
-import { ChartImplementation } from "../charts/chart";
+import { ChartImplementation, type PluginConfig } from "../charts/chart";
 import { ZoomController } from "../interaction/zoom-controller";
 import type { InitMsg, InteractionEvent, LoadAndRenderMsg, WorkerMsg } from "../transport/protocol";
+import { type TileSourceSpec } from "../map/tile-source";
 export declare class WorkerRenderer {
     chartImpl: ChartImplementation;
     glManager: WebGLContextManager;
@@ -13,6 +14,17 @@ export declare class WorkerRenderer {
     cssWidth: number;
     cssHeight: number;
     dpr: number;
+    /**
+     * Blit-mode compose surface: gridlines + GL frame + chrome are
+     * drawn here each `endFrame` and shipped as ONE `ImageBitmap`, so
+     * every layer rides the host's staged-present hold (see
+     * `InitMsg.gridlinesCanvas`). `null` in direct mode.
+     */
+    private _composeCanvas;
+    private _composeCtx;
+    private _lastPlot;
+    private _frameSerial;
+    private _overlayPresentQueued;
     client: Client;
     view: View;
     /**
@@ -42,6 +54,13 @@ export declare class WorkerRenderer {
     private _lastDragY;
     constructor(msg: InitMsg, client: Client, view: View, table: Table | null, controlPort: MessagePort, ImplClass: new () => ChartImplementation);
     setViewByName(name: string): void;
+    /**
+     * Registry write precedes the config apply — `cfg` may name the
+     * spec riding alongside it (see `SetPluginConfigMsg.tileSource`),
+     * and a replaced template must be registered first so the map
+     * chart's rebind sees the new content-derived cache id.
+     */
+    setPluginConfig(cfg: PluginConfig, tileSource?: TileSourceSpec): void;
     /**
      * Full data-fetch + render pipeline. Owns every `Client`/`Table`/
      * `View` await on the render path:
@@ -97,13 +116,39 @@ export declare class WorkerRenderer {
      * facet grid and controllers, so the resolution runs here.
      */
     private _resolveTarget;
+    /**
+     * Legend-first interaction routing. The chart's `LegendController`
+     * sees every forwarded event BEFORE the zoom / tooltip paths, so
+     * legend gestures (scroll, width drag, floating move / resize)
+     * structurally preempt plot pan / zoom / hover — a wheel over the
+     * legend can never zoom the plot under it, and a floating-panel
+     * drag can never start a pan.
+     */
+    private _legendInteraction;
     onInteraction(event: InteractionEvent): void;
+    private _routeInteraction;
     /**
      * Read the chart impl's `TooltipController`. Charts that don't use
      * one (no `attachTooltip` override) yield `null` and the
      * mouse-event branches fall through.
      */
     private _tooltip;
+    /**
+     * Blit-mode frame composite: draw the gridlines (bottom), the GL
+     * plot bitmap (middle) and the chrome/axes (top) into the compose
+     * surface and transfer the result — the single `ImageBitmap` the
+     * host blits, and the unit the staged-present hold stages. Runs in
+     * `endFrame`, which the scheduler orders after `render2D`'s 2D
+     * flush, so both layers hold this frame's content.
+     *
+     * A layer whose buffer differs from the plot's dimensions is
+     * skipped rather than scaled: its content is a stale-sized frame
+     * mid-resize (the 2D draws re-size their canvas to `css × dpr` on
+     * the next flush), and scaling it would re-introduce exactly the
+     * warp this composite exists to prevent.
+     */
+    private _composeFrame;
+    private _presentOverlay;
     /**
      * Composite the three layers into a single PNG `Blob`.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perspective-dev/viewer-charts",
-  "version": "5.2.0",
+  "version": "5.3.1",
   "description": "Perspective.js WebGL Plugin",
   "unpkg": "./dist/cdn/perspective-viewer-charts.js",
   "jsdelivr": "./dist/cdn/perspective-viewer-charts.js",

package/src/css/perspective-viewer-charts.css

@@ -89,7 +89,6 @@
     border-radius: 3px;
     padding: 3px;
     overflow-y: auto;
-    white-space: pre;
     z-index: 10;
     line-height: 16px;
 }

package/src/ts/axis/bar-axis.ts

@@ -12,7 +12,7 @@
 
 import type { Canvas2D, Context2D } from "../charts/canvas-types";
 import { PlotLayout } from "../layout/plot-layout";
-import { formatTickValue, formatDateTickValue } from "../layout/ticks";
+import { stepTickFormatter } from "../layout/ticks";
 import { initCanvas } from "./canvas";
 import {
     renderCategoricalXTicks,
@@ -37,12 +37,7 @@ function tickFormatter(
         return override;
     }
 
-    if (!domain.isDate) {
-        return formatTickValue;
-    }
-
-    const step = ticks.length > 1 ? ticks[1] - ticks[0] : 0;
-    return (v: number) => formatDateTickValue(v, step);
+    return stepTickFormatter(domain.isDate, ticks);
 }
 
 /**