@perspective-dev/viewer-charts 5.3.0 → 5.4.0

package/src/ts/map/tile-source.ts

@@ -10,6 +10,8 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+import TILE_SOURCE_SEED from "./tile-sources.json";
+
 /**
  * A tile source describes *where* to fetch raster XYZ tiles and what
  * attribution text the renderer must display in the chrome canvas.
@@ -84,73 +86,217 @@ export class TemplatedTileSource implements TileSource {
 }
 
 /**
- * Identifier of the default tile providers shipped with `viewer-charts`.
- * Surfaced as the `map_tile_provider` PluginConfig enum so users can
- * pick light vs. dark vs. labels-only without writing a custom source.
+ * Declarative description of one raster XYZ tile provider — the shape
+ * of an entry in [tile-sources.json] and of the argument to
+ * `registerTileSource`. Everything the renderer needs to construct a
+ * concrete {@link TileSource} lives here; the TypeScript is generic
+ * over these entries and hardcodes no provider URLs.
  */
-export type TileProviderId =
-    | "carto-positron"
-    | "carto-dark-matter"
-    | "carto-voyager";
+export interface TileSourceSpec {
+    /** Registry key; the persisted `map_tile_provider` value. */
+    readonly id: string;
+
+    /** Human-readable enum-variant label on the settings panel. */
+    readonly label: string;
+
+    /**
+     * URL template with `{z}`/`{x}`/`{y}` placeholders and optional
+     * `{s}` subdomain rotation. A provider that needs an API key
+     * embeds it directly in the template it registers — keys never
+     * pass through `plugin_config`, so they never appear in `save()`
+     * output.
+     */
+    readonly template: string;
+
+    /** `{s}` rotation pool; required non-empty iff `template` has `{s}`. */
+    readonly subdomains: readonly string[];
+
+    /** See {@link TileSource.attribution}. */
+    readonly attribution: string;
+
+    /** See {@link TileSource.tileSize}. Default 256. */
+    readonly tile_size: number;
+
+    /** See {@link TileSource.maxZoom}. Default 19. */
+    readonly max_zoom: number;
+}
 
 /**
- * CartoDB's "Positron" basemap — light, low-contrast, designed to sit
- * behind a chart overlay. Default for light themes.
+ * Validate + normalize an untrusted spec (a JSON entry or a
+ * `registerTileSource` argument). Throws `TypeError` naming the
+ * offending field; returns a frozen spec with defaults applied.
  */
-function cartoPositron(): TileSource {
-    return new TemplatedTileSource(
-        "carto-positron",
-        "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
-        "© OpenStreetMap contributors © CARTO",
-        256,
-        19,
-        ["a", "b", "c", "d"],
-    );
+export function parseTileSourceSpec(input: unknown): TileSourceSpec {
+    if (typeof input !== "object" || input === null) {
+        throw new TypeError("TileSourceSpec must be an object");
+    }
+
+    const raw = input as Record<string, unknown>;
+    const str = (key: string): string => {
+        const v = raw[key];
+        if (typeof v !== "string" || v.length === 0) {
+            throw new TypeError(
+                `TileSourceSpec.${key} must be a non-empty string`,
+            );
+        }
+
+        return v;
+    };
+
+    const id = str("id");
+    const label = str("label");
+    const template = str("template");
+    const attribution = str("attribution");
+    for (const placeholder of ["{z}", "{x}", "{y}"]) {
+        if (!template.includes(placeholder)) {
+            throw new TypeError(
+                `TileSourceSpec.template must contain "${placeholder}"`,
+            );
+        }
+    }
+
+    const rawSubdomains = raw["subdomains"] ?? [];
+    if (
+        !Array.isArray(rawSubdomains) ||
+        rawSubdomains.some((s) => typeof s !== "string" || s.length === 0)
+    ) {
+        throw new TypeError(
+            "TileSourceSpec.subdomains must be an array of non-empty strings",
+        );
+    }
+
+    const subdomains = Object.freeze([...rawSubdomains] as string[]);
+    if (template.includes("{s}") && subdomains.length === 0) {
+        throw new TypeError(
+            'TileSourceSpec.template uses "{s}" but no subdomains were given',
+        );
+    }
+
+    const num = (key: string, dflt: number): number => {
+        const v = raw[key];
+        if (v === undefined) {
+            return dflt;
+        }
+
+        if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) {
+            throw new TypeError(
+                `TileSourceSpec.${key} must be a positive number`,
+            );
+        }
+
+        return v;
+    };
+
+    return Object.freeze({
+        id,
+        label,
+        template,
+        subdomains,
+        attribution,
+        tile_size: num("tile_size", 256),
+        max_zoom: num("max_zoom", 19),
+    });
 }
 
 /**
- * CartoDB's "Dark Matter" basemap — dark, low-contrast. Default for
- * dark themes.
+ * 32-bit FNV-1a over a string, hex-encoded. Fingerprints a spec's
+ * fetch-relevant fields into the {@link TileSource.id} cache key.
  */
-function cartoDarkMatter(): TileSource {
-    return new TemplatedTileSource(
-        "carto-dark-matter",
-        "https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
-        "© OpenStreetMap contributors © CARTO",
-        256,
-        19,
-        ["a", "b", "c", "d"],
-    );
+function fnv1a(s: string): string {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+
+    return (h >>> 0).toString(16);
 }
 
 /**
- * CartoDB's "Voyager" basemap — full color, more land/water contrast
- * than Positron. Good when the chart glyphs are translucent.
+ * The set of known tile providers: the bundled entries from
+ * [tile-sources.json] plus any registered at runtime via
+ * `registerTileSource`. One instance exists per JS realm ({@link
+ * TILE_SOURCES}) — the plugin realm's is the source of truth for the
+ * settings-panel enum; the worker realm's resolves ids at render time.
+ * The realms need no eager mirroring: every `setPluginConfig` / `init`
+ * control message carries the resolved spec for the config's
+ * `map_tile_provider` alongside the config itself, so a worker can
+ * never hold a config whose spec it lacks.
  */
-function cartoVoyager(): TileSource {
-    return new TemplatedTileSource(
-        "carto-voyager",
-        "https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png",
-        "© OpenStreetMap contributors © CARTO",
-        256,
-        19,
-        ["a", "b", "c", "d"],
-    );
+export class TileSourceRegistry {
+    private _specs = new Map<string, TileSourceSpec>();
+
+    constructor(seed: readonly unknown[]) {
+        for (const entry of seed) {
+            const spec = parseTileSourceSpec(entry);
+            this._specs.set(spec.id, spec);
+        }
+    }
+
+    /**
+     * Add (or replace, by id) a provider. Validates via
+     * {@link parseTileSourceSpec} and returns the normalized spec.
+     * Replacement is safe for live charts: the cache identity below is
+     * content-derived, so a changed template yields a new cache key
+     * and the tile layer drops its stale textures on next bind.
+     */
+    register(input: unknown): TileSourceSpec {
+        const spec = parseTileSourceSpec(input);
+        this._specs.set(spec.id, spec);
+        return spec;
+    }
+
+    /** Every known spec, bundled first, in insertion order. */
+    list(): readonly TileSourceSpec[] {
+        return [...this._specs.values()];
+    }
+
+    /** The spec registered under `id`, or `undefined` if unknown. */
+    specFor(id: string): TileSourceSpec | undefined {
+        return this._specs.get(id);
+    }
+
+    /**
+     * Resolve a `map_tile_provider` id to a concrete `TileSource`.
+     * Unknown ids fall back to the first bundled entry so a
+     * misconfigured `plugin_config` never produces a blank map — and
+     * so a config restored *before* its custom source is registered
+     * degrades to the default basemap until the next config forward
+     * carries the registered spec.
+     */
+    sourceFor(id: string): TileSource {
+        const spec = this._specs.get(id) ?? this._specs.values().next().value!;
+
+        // Cache identity = id + content hash of the fetch-relevant
+        // fields. Re-registering an id with a different template MUST
+        // invalidate `TileCache` entries (keyed on `TileSource.id`)
+        // or stale tiles from the old URL would keep rendering; the
+        // hash does that without any cross-realm revision state.
+        const fingerprint = fnv1a(
+            `${spec.template}${spec.subdomains.join(",")}`,
+        );
+
+        return new TemplatedTileSource(
+            `${spec.id}@${fingerprint}`,
+            spec.template,
+            spec.attribution,
+            spec.tile_size,
+            spec.max_zoom,
+            spec.subdomains,
+        );
+    }
 }
 
 /**
- * Resolve a `TileProviderId` (from PluginConfig) to a concrete
- * `TileSource`. Unknown ids fall back to Positron so a misconfigured
- * `_pluginConfig` never produces a blank map.
+ * Realm-wide provider registry, seeded from [tile-sources.json]. A
+ * malformed bundled entry fails loudly here, at first import.
  */
-export function tileSourceFor(id: TileProviderId | string): TileSource {
-    switch (id) {
-        case "carto-dark-matter":
-            return cartoDarkMatter();
-        case "carto-voyager":
-            return cartoVoyager();
-        case "carto-positron":
-        default:
-            return cartoPositron();
-    }
+export const TILE_SOURCES = new TileSourceRegistry(TILE_SOURCE_SEED);
+
+/**
+ * Read-only listing of every known tile provider (bundled + runtime-
+ * registered), in settings-panel enum order. Public package export.
+ */
+export function tileSources(): readonly TileSourceSpec[] {
+    return TILE_SOURCES.list();
 }

package/src/ts/map/tile-sources.json

@@ -0,0 +1,18 @@
+[
+    {
+        "id": "osm",
+        "label": "OpenStreetMap",
+        "template": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+        "attribution": "© OpenStreetMap contributors",
+        "tile_size": 256,
+        "max_zoom": 19
+    },
+    {
+        "id": "versatiles-satellite",
+        "label": "Satellite (VersaTiles)",
+        "template": "https://tiles.versatiles.org/tiles/satellite/{z}/{x}/{y}",
+        "attribution": "© VersaTiles (versatiles.org/sources)",
+        "tile_size": 256,
+        "max_zoom": 12
+    }
+]

package/src/ts/plugin/charts.ts

@@ -95,11 +95,27 @@ const Y_AXIS = ["Y Axis"];
 const SELECT = "select";
 const TOGGLE = "toggle";
 
-const DEFAULT_MAX_CELLS = 2_000_000;
+const DEFAULT_MAX_CELLS = 10_000_000;
 const DEFAULT_MAX_COLUMNS = 10_000;
 
 //  Plugin-config field sets, by chart family.
 //
+export const LEGEND_FIELDS: readonly PluginConfigField[] = [
+    "legend_mode",
+    "legend_size_mode",
+    "legend_width_px",
+    "legend_height_px",
+    "legend_anchor",
+    "legend_x",
+    "legend_y",
+    "legend_opacity",
+];
+
+export const TOOLTIP_FIELDS: readonly PluginConfigField[] = [
+    "tooltip_max_column_px",
+    "tooltip_opacity",
+];
+
 // Series charts paint bars / lines / scatter / area glyphs (selected
 // per-column via `chart_type`), so the union covers every glyph that
 // might appear. `auto_alt_y_axis` + `series_zoom_mode` are Series-only.
@@ -113,6 +129,8 @@ const SERIES_FIELDS: readonly PluginConfigField[] = [
     "point_size_px",
     "band_inner_frac",
     "bar_inner_pad",
+    ...LEGEND_FIELDS,
+    ...TOOLTIP_FIELDS,
 ];
 
 // The band pipeline's historical split_by rendering is a single plot
@@ -137,6 +155,8 @@ const CARTESIAN_FIELDS: readonly PluginConfigField[] = [
     "domain_mode",
     "line_width_px",
     "point_size_px",
+    ...LEGEND_FIELDS,
+    ...TOOLTIP_FIELDS,
 ];
 
 // Candlestick/OHLC share the categorical-X build pipeline (band slots)
@@ -149,13 +169,20 @@ const FIN_FIELDS: readonly PluginConfigField[] = [
     "bar_inner_pad",
     "wick_width_px",
     "ohlc_line_width_px",
+    ...TOOLTIP_FIELDS,
 ];
 
-// Hierarchical — none of the listed fields apply.
-const NO_FIELDS: readonly PluginConfigField[] = [];
+const TREE_FIELDS: readonly PluginConfigField[] = [
+    ...LEGEND_FIELDS,
+    ...TOOLTIP_FIELDS,
+];
 
 // Heatmap
-const HEATMAP_FIELDS: readonly PluginConfigField[] = ["facet_zoom_mode"];
+const HEATMAP_FIELDS: readonly PluginConfigField[] = [
+    "facet_zoom_mode",
+    ...LEGEND_FIELDS,
+    ...TOOLTIP_FIELDS,
+];
 
 // Map — reuses the cartesian build pipeline with a Mercator
 // projection hook. Carries the basemap controls (`map_tile_provider`,
@@ -168,6 +195,9 @@ const MAP_BASE_FIELDS: readonly PluginConfigField[] = [
     "domain_mode",
     "map_tile_provider",
     "map_tile_alpha",
+    "numeric_axes",
+    ...LEGEND_FIELDS,
+    ...TOOLTIP_FIELDS,
 ];
 const MAP_SCATTER_FIELDS: readonly PluginConfigField[] = [
     ...MAP_BASE_FIELDS,
@@ -197,6 +227,8 @@ const DENSITY_FIELDS: readonly PluginConfigField[] = [
     "gradient_radius_px",
     "gradient_intensity",
     "gradient_heat_max",
+    ...LEGEND_FIELDS,
+    ...TOOLTIP_FIELDS,
 ];
 
 function make(
@@ -314,14 +346,16 @@ const CHARTS: ChartTypeConfig[] = [
         DENSITY_FIELDS,
         { ...CART_ROLES },
     ),
-    make("Treemap", "treemap", HIER, TOGGLE, 1, HIER_NAMES, NO_FIELDS, {
+    make("Treemap", "treemap", HIER, TOGGLE, 1, HIER_NAMES, TREE_FIELDS, {
         ...HIER_ROLES,
+        plugin_field_defaults: { legend_mode: "sidebar" },
     }),
-    make("Sunburst", "sunburst", HIER, TOGGLE, 1, HIER_NAMES, NO_FIELDS, {
+    make("Sunburst", "sunburst", HIER, TOGGLE, 1, HIER_NAMES, TREE_FIELDS, {
         ...HIER_ROLES,
     }),
     make("Heatmap", "heatmap", HIER, SELECT, 1, ["Color"], HEATMAP_FIELDS, {
         ...HEATMAP_ROLES,
+        plugin_field_defaults: { legend_mode: "sidebar" },
     }),
     make("Candlestick", "candlestick", FIN, TOGGLE, 1, FIN_NAMES, FIN_FIELDS, {
         ...FIN_ROLES,

package/src/ts/plugin/format-defaults.ts

@@ -0,0 +1,37 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 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 const CHART_NUMBER_DEFAULTS: NumberFormatConfig = {
+    notation: "compact",
+    compactDisplay: "short",
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 1,
+};
+
+export const CHART_DATETIME_DEFAULTS: DateFormatConfig = {
+    dateStyle: "medium",
+    timeStyle: "disabled",
+};
+
+export const CHART_DATE_DEFAULTS: DateFormatConfig = {
+    dateStyle: "medium",
+};