@perspective-dev/viewer-charts 5.2.0 → 5.3.1

package/src/ts/theme/gradient.ts

@@ -10,7 +10,7 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { parseCSSColorToVec3 } from "../utils/css";
+import { parseCSSColorToVec3, vec3ToHexColor } from "../utils/css";
 
 /**
  * A single stop on a parsed CSS gradient. `offset` ∈ [0, 1].
@@ -178,6 +178,246 @@ export function parseCssGradient(
     return result;
 }
 
+/**
+ * A color literal — `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` or
+ * `rgba()` — as a `[0, 1]` RGB triple, or `null` for anything else.
+ */
+export function parseCssColorStrict(
+    src: string,
+): [number, number, number] | null {
+    const s = src.trim();
+    if (s.startsWith("#")) {
+        const hex = s.slice(1);
+        if (!/^[0-9a-f]+$/i.test(hex)) {
+            return null;
+        }
+
+        if (hex.length === 3 || hex.length === 4) {
+            return [
+                parseInt(hex[0] + hex[0], 16) / 255,
+                parseInt(hex[1] + hex[1], 16) / 255,
+                parseInt(hex[2] + hex[2], 16) / 255,
+            ];
+        }
+
+        if (hex.length === 6 || hex.length === 8) {
+            return [
+                parseInt(hex.slice(0, 2), 16) / 255,
+                parseInt(hex.slice(2, 4), 16) / 255,
+                parseInt(hex.slice(4, 6), 16) / 255,
+            ];
+        }
+
+        return null;
+    }
+
+    const m = s.match(/^rgba?\(([^)]*)\)$/i);
+    if (!m) {
+        return null;
+    }
+
+    const tokens = m[1]
+        .split("/")[0]
+        .split(/[\s,]+/)
+        .filter((x) => x.length > 0);
+    if (tokens.length < 3 || tokens.length > 4) {
+        return null;
+    }
+
+    const channel = (token: string): number | null => {
+        const pct = token.endsWith("%");
+        const n = parseFloat(pct ? token.slice(0, -1) : token);
+        if (!isFinite(n)) {
+            return null;
+        }
+
+        const v = pct ? (n / 100) * 255 : n;
+        return Math.max(0, Math.min(255, Math.round(v))) / 255;
+    };
+
+    const r = channel(tokens[0]);
+    const g = channel(tokens[1]);
+    const b = channel(tokens[2]);
+    return r === null || g === null || b === null ? null : [r, g, b];
+}
+
+/**
+ * The shared `linear-gradient(...)` tokenizer of the viewer's CSS-valued
+ * config grammar.
+ */
+export function tokenizeLinearGradient(
+    src: string,
+): Array<[[number, number, number], number | null]> | null {
+    const m = src.trim().match(/^linear-gradient\s*\((.*)\)$/is);
+    if (!m) {
+        return null;
+    }
+
+    const body = m[1];
+    const parts: string[] = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch === "(") {
+            depth++;
+        } else if (ch === ")") {
+            depth--;
+        } else if (ch === "," && depth === 0) {
+            parts.push(body.substring(start, i));
+            start = i + 1;
+        }
+    }
+
+    parts.push(body.substring(start));
+    const out: Array<[[number, number, number], number | null]> = [];
+    for (let i = 0; i < parts.length; i++) {
+        const piece = parts[i].trim();
+        if (!piece) {
+            return null;
+        }
+
+        const lower = piece.toLowerCase();
+        if (
+            i === 0 &&
+            (lower.startsWith("to ") ||
+                /^[-\d.]+(deg|rad|grad|turn)$/.test(lower))
+        ) {
+            continue;
+        }
+
+        const posMatch = piece.match(/\s([^\s)]+)$/);
+        let color = piece;
+        let offset: number | null = null;
+        if (posMatch) {
+            const tail = posMatch[1];
+            if (tail.endsWith("%")) {
+                const n = parseFloat(tail.slice(0, -1));
+                if (!isFinite(n)) {
+                    return null;
+                }
+
+                color = piece.substring(0, posMatch.index).trim();
+                offset = n / 100;
+            } else if (/^[-\d.]/.test(tail)) {
+                return null;
+            }
+        }
+
+        const rgb = parseCssColorStrict(color);
+        if (!rgb) {
+            return null;
+        }
+
+        out.push([rgb, offset]);
+    }
+
+    return out;
+}
+
+/**
+ * Strict gradient reader: a `linear-gradient(...)` with ≥ 2 stops,
+ * positions optional, offsets clamped to `[0, 1]` and sorted, or `null`
+ * on malformed input.
+ */
+export function parseCssGradientStrict(src: string): GradientStop[] | null {
+    const entries = tokenizeLinearGradient(src);
+    if (!entries || entries.length < 2) {
+        return null;
+    }
+
+    const offsets: Array<number | null> = entries.map(([, p]) => p);
+    const last = offsets.length - 1;
+    if (offsets[0] === null) {
+        offsets[0] = 0;
+    }
+
+    if (offsets[last] === null) {
+        offsets[last] = 1;
+    }
+
+    for (let i = 1; i < last; i++) {
+        if (offsets[i] !== null) {
+            continue;
+        }
+
+        let j = i + 1;
+        while (offsets[j] === null) {
+            j++;
+        }
+
+        const before = offsets[i - 1]!;
+        const after = offsets[j]!;
+        const span = j - (i - 1);
+        for (let k = i; k < j; k++) {
+            offsets[k] = before + ((k - (i - 1)) / span) * (after - before);
+        }
+
+        i = j - 1;
+    }
+
+    const stops: GradientStop[] = entries.map(([rgb], i) => ({
+        offset: Math.max(0, Math.min(1, offsets[i]!)),
+        color: [rgb[0], rgb[1], rgb[2], 1],
+    }));
+
+    stops.sort((a, b) => a.offset - b.offset);
+    return stops;
+}
+
+/**
+ * Strict palette reader: a `linear-gradient(...)` of ≥ 1 colors with no
+ * positions, or `null` on malformed input.
+ */
+export function parseCssColorList(
+    src: string,
+): Array<[number, number, number]> | null {
+    const entries = tokenizeLinearGradient(src);
+    if (!entries || entries.length === 0) {
+        return null;
+    }
+
+    const out: Array<[number, number, number]> = [];
+    for (const [rgb, offset] of entries) {
+        if (offset !== null) {
+            return null;
+        }
+
+        out.push(rgb);
+    }
+
+    return out;
+}
+
+function formatPercent(offset: number): string {
+    const rounded = Math.round(Math.max(0, Math.min(1, offset)) * 1000) / 10;
+    return `${rounded}%`;
+}
+
+/**
+ * The viewer's canonical gradient string for `stops`: `linear-gradient(to
+ * right, #rrggbb P%, …)`, sorted, positions at 0.1% resolution.
+ */
+export function stopsToCss(stops: GradientStop[]): string {
+    const body = [...stops]
+        .sort((a, b) => a.offset - b.offset)
+        .map(
+            (stop) =>
+                `${vec3ToHexColor([stop.color[0], stop.color[1], stop.color[2]])} ${formatPercent(stop.offset)}`,
+        )
+        .join(", ");
+
+    return `linear-gradient(to right, ${body})`;
+}
+
+/**
+ * The viewer's canonical palette string for `colors`: the same frame
+ * with bare `#rrggbb` entries and no positions.
+ */
+export function colorsToCss(colors: Array<[number, number, number]>): string {
+    return `linear-gradient(to right, ${colors.map(vec3ToHexColor).join(", ")})`;
+}
+
 /**
  * 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]`.
@@ -257,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/theme/overrides.ts

@@ -0,0 +1,76 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import {
+    parseCssColorList,
+    parseCssGradientStrict,
+    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 function applyColumnColorOverrides(
+    theme: Theme,
+    columnsConfig: Record<string, any> | undefined,
+    colorColumn: string | null,
+): Theme {
+    if (!colorColumn) {
+        return theme;
+    }
+
+    const cfg = columnsConfig?.[colorColumn];
+    if (!cfg) {
+        return theme;
+    }
+
+    let out = theme;
+    const gradient = parseGradientOverride(cfg.gradient);
+    if (gradient) {
+        out = { ...out, gradientStops: gradient };
+    }
+
+    const palette = parsePaletteOverride(cfg.palette);
+    if (palette) {
+        out = { ...out, seriesPalette: palette };
+    }
+
+    return out;
+}
+
+/**
+ * Parse a stored `palette` value into the `seriesPalette` shape, or
+ * `null` on anything malformed.
+ */
+export function parsePaletteOverride(raw: unknown): Vec3[] | null {
+    if (typeof raw !== "string") {
+        return null;
+    }
+
+    return parseCssColorList(raw);
+}
+
+/**
+ * Parse a stored `gradient` value into sorted `GradientStop[]`, or
+ * `null` on malformed input or fewer than 2 stops.
+ */
+export function parseGradientOverride(raw: unknown): GradientStop[] | null {
+    if (typeof raw !== "string") {
+        return null;
+    }
+
+    return parseCssGradientStrict(raw);
+}

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
@@ -100,8 +102,20 @@ 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 —
@@ -173,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.
      */
@@ -259,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 {
@@ -305,6 +342,7 @@ export interface LoadAndRenderMsg {
 export interface LoadAndRenderAckMsg {
     kind: "loadAndRenderAck";
     msgId: number;
+    error?: string;
 }
 
 export interface RedrawMsg {
@@ -405,7 +443,8 @@ export interface SnapshotPngReqMsg {
 export interface SnapshotPngReplyMsg {
     kind: "snapshotPngReply";
     requestId: number;
-    blob: Blob;
+    blob?: Blob;
+    error?: string;
 }
 
 export interface DestroyMsg {
@@ -469,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 };
 }
@@ -489,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