Configurable legends for viewer-charts

docs/md/SUMMARY.md

@@ -44,6 +44,7 @@
     - [Saving and restoring UI state](./how_to/javascript/save_restore.md)
     - [Listening for events](./how_to/javascript/events.md)
     - [Plugin render limits](./how_to/javascript/plugin_settings.md)
+    - [Map tile sources](./how_to/javascript/map_tile_sources.md)
     - [Configuring the LLM agent](./how_to/javascript/agent.md)
 - [Virtual Servers](./how_to/javascript/virtual_server.md)
     - [DuckDB](./how_to/javascript/virtual_server/duckdb.md)

docs/md/how_to/javascript/map_tile_sources.md

@@ -0,0 +1,51 @@
+# Map tile sources
+
+The map plugins (`Map Scatter`, `Map Line`, `Map Density`) draw their glyphs
+over a raster XYZ basemap. Which basemap is used is controlled by the
+`map_tile_provider` `plugin_config` field, an enum of _tile sources_ — each a
+small metadata record describing where to fetch tiles and how to attribute them.
+Two providers ship with `@perspective-dev/viewer-charts`:
+
+- `osm` OpenStreetMap's standard raster tiles (the default)
+- `versatiles-satellite` Global satellite imagery from
+  [VersaTiles](https://versatiles.org)
+
+## Registering a custom tile source
+
+Any raster XYZ provider can be added at runtime with `registerTileSource`,
+exported from the `@perspective-dev/viewer-charts` module. Registered sources
+appear in the settings panel's "Map provider" control alongside the bundled ones
+and are available to every current and future map chart. For example, the
+[CARTO](https://carto.com) basemaps:
+
+```javascript
+import { registerTileSource } from "@perspective-dev/viewer-charts";
+
+for (const [id, label, path] of [
+    ["carto-positron", "Light (Positron)", "light_all"],
+    ["carto-dark-matter", "Dark Matter", "dark_all"],
+    ["carto-voyager", "Voyager", "rastertiles/voyager"],
+]) {
+    registerTileSource({
+        id,
+        label,
+        template: `https://{s}.basemaps.cartocdn.com/${path}/{z}/{x}/{y}.png?api_key=CARTO_API_KEY`,
+        subdomains: ["a", "b", "c", "d"],
+        attribution: "© OpenStreetMap contributors © CARTO",
+        tile_size: 256,
+        max_zoom: 19,
+    });
+}
+```
+
+If you consume the plugin as a registered Custom Element rather than an ES
+module, the same function is available as a static on the plugin element class:
+
+```javascript
+customElements
+    .get("perspective-viewer-charts-map-scatter")
+    .registerTileSource({ ... });
+```
+
+`tileSources()` (also exported, and available as a static) returns the current
+list of registered specs.

docs/src/data/projects/blocks.ts

@@ -626,7 +626,6 @@ export const SF_PROJECTS: Project[] = [
             },
             plugin: "Map Density",
             plugin_config: {
-                map_tile_provider: "carto-dark-matter",
                 gradient_radius_px: 15,
                 gradient_intensity: 1,
             },
@@ -658,9 +657,6 @@ export const SF_PROJECTS: Project[] = [
         workspace: singlePanel({
             columns_config: {},
             plugin: "Map Scatter",
-            plugin_config: {
-                map_tile_provider: "carto-dark-matter",
-            },
             table: "evictions",
             theme: null,
             title: null,

docs/src/data/tile_sources.ts

@@ -0,0 +1,61 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { registerTileSource } from "@perspective-dev/viewer-charts";
+
+/**
+ * The CARTO basemaps, registered through the public `viewer-charts`
+ * tile-source API so the docs site's map examples offer them alongside
+ * the bundled providers. They live here rather than in the library's
+ * bundled metadata — this file doubles as the worked example for the
+ * "Map tile sources" guide page (how_to/javascript/map_tile_sources.md);
+ * keep the two in sync, except the guide's templates append a
+ * placeholder `?api_key=CARTO_API_KEY` to illustrate keyed providers —
+ * these live registrations stay key-less (the public CARTO basemaps
+ * don't require one).
+ */
+const CARTO_TILE_SOURCES = [
+    {
+        id: "carto-positron",
+        label: "Light (Positron)",
+        template: "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
+        subdomains: ["a", "b", "c", "d"],
+        attribution: "© OpenStreetMap contributors © CARTO",
+        tile_size: 256,
+        max_zoom: 19,
+    },
+    {
+        id: "carto-dark-matter",
+        label: "Dark Matter",
+        template: "https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
+        subdomains: ["a", "b", "c", "d"],
+        attribution: "© OpenStreetMap contributors © CARTO",
+        tile_size: 256,
+        max_zoom: 19,
+    },
+    {
+        id: "carto-voyager",
+        label: "Voyager",
+        template:
+            "https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png",
+        subdomains: ["a", "b", "c", "d"],
+        attribution: "© OpenStreetMap contributors © CARTO",
+        tile_size: 256,
+        max_zoom: 19,
+    },
+];
+
+export function registerCartoTileSources(): void {
+    for (const spec of CARTO_TILE_SOURCES) {
+        registerTileSource(spec);
+    }
+}

docs/src/index.ts

@@ -21,13 +21,15 @@ import { initSourceModal } from "./components/source_modal.js";
 import { initSqlDrawer } from "./components/sql_drawer.js";
 import { bindViewer } from "./data/engines.js";
 import { initTheme } from "./data/theme.js";
+import { registerCartoTileSources } from "./data/tile_sources.js";
 import type { HTMLPerspectiveViewerElement } from "@perspective-dev/viewer";
 
 const shell = document.getElementById("app")!;
 const viewer = document.getElementById(
     "viewer",
 ) as HTMLPerspectiveViewerElement;
 
+registerCartoTileSources();
 bindViewer(viewer);
 void initTheme(viewer);