@perspective-dev/viewer-charts 4.3.0

package/dist/esm/layout/facet-grid.d.ts

@@ -0,0 +1,126 @@
+import { PlotLayout, type PlotRect } from "./plot-layout";
+/**
+ * Tri-state axis mode.
+ *
+ *   - `"outer"` — one shared axis band reserved at the grid edge;
+ *     `outerXAxisRect` / `outerYAxisRect` populated, per-cell gutter
+ *     collapsed to 0 on that side. Caller paints the shared axis
+ *     once per frame using the grid's outer rect.
+ *   - `"cell"` — every cell reserves its own gutter on that side;
+ *     caller paints one axis per cell. Outer rect is undefined.
+ *   - `"none"` — no gutter anywhere on that side: neither an outer
+ *     band nor a per-cell reservation. Intended for chart types with
+ *     no numeric axis at all (treemap, sunburst). When BOTH axes are
+ *     `"none"` cells are also made flush on the right so adjacent
+ *     plot rects share a boundary.
+ *
+ * Defaults to `"cell"` when undefined.
+ */
+export type AxisMode = "outer" | "cell" | "none";
+export interface FacetGridOptions {
+    cssWidth: number;
+    cssHeight: number;
+    /**
+     * See {@link AxisMode}. Default `"cell"`.
+     */
+    xAxis?: AxisMode;
+    /**
+     * See {@link AxisMode}. Default `"cell"`.
+     */
+    yAxis?: AxisMode;
+    /**
+     * Reserve a right gutter for a single shared legend.
+     */
+    hasLegend?: boolean;
+    /** Axis-label allowance (consumed only when the corresponding axis
+     *  mode produces a gutter — outer band or per-cell). */
+    hasXLabel?: boolean;
+    hasYLabel?: boolean;
+    /**
+     * Per-facet title strip height (px). 0 disables.
+     */
+    titleBand?: number;
+    /**
+     * Pixel gap between adjacent cells. Carved out of the grid
+     * interior before cell sizing; outer edges of the leftmost /
+     * rightmost columns and top / bottom rows are unaffected. Default
+     * 0 (flush cells).
+     */
+    gap?: number;
+}
+export interface FacetCell {
+    index: number;
+    label: string;
+    /**
+     * Sub-plot layout. Every cell in a grid has *identical*
+     * `plotRect.width` and `plotRect.height` — cell internal margins
+     * do not vary by edge position. Shared-axis gutters live in
+     * `FacetGrid.outerXAxisRect` / `outerYAxisRect` instead, painted
+     * once per frame by the caller.
+     */
+    layout: PlotLayout;
+    /**
+     * Title strip above the facet's plot rect, if `titleBand > 0`.
+     */
+    titleRect?: PlotRect;
+    isLeftEdge: boolean;
+    isBottomEdge: boolean;
+}
+export interface FacetGrid {
+    cells: FacetCell[];
+    /**
+     * Right-gutter rect for the shared legend.
+     */
+    legendRect?: PlotRect;
+    /**
+     * Outer band reserved for the shared X axis (ticks + label). Only
+     * set when `xAxis === "outer"`. Spans the grid interior's
+     * horizontal extent and sits immediately below the bottom row of
+     * cells.
+     */
+    outerXAxisRect?: PlotRect;
+    /**
+     * Outer band reserved for the shared Y axis (ticks + label). Only
+     * set when `yAxis === "outer"`. Spans the grid interior's
+     * vertical extent and sits immediately left of the leftmost
+     * column of cells.
+     */
+    outerYAxisRect?: PlotRect;
+}
+/**
+ * Collect the bottom-row cells' `PlotLayout`s — i.e. the cells that
+ * sit on the grid's bottom edge. Shared-X axis renderers paint X
+ * ticks aligned to each of these. Empty when the grid has zero cells.
+ */
+export declare function bottomRowLayouts(grid: FacetGrid): PlotLayout[];
+/**
+ * Collect the left-column cells' `PlotLayout`s — symmetric to
+ * {@link bottomRowLayouts} for the shared-Y axis path.
+ */
+export declare function leftColumnLayouts(grid: FacetGrid): PlotLayout[];
+/**
+ * Arrange `labels.length` sub-plots in a row-major grid sized to fit
+ * `(cssWidth, cssHeight)`.
+ *
+ * Grid shape is chosen to minimize cell aspect distance from square
+ * given the container's grid interior: `cols ∈ [1, count]`,
+ * `rows = ceil(count / cols)`, tie-broken toward fewer total cells.
+ *
+ * **Invariant:** every `cells[i].layout.plotRect` has the same
+ * `width` and `height`. Shared-axis gutters are carved out of the
+ * outer canvas BEFORE cell sizing, so a cell's edge position never
+ * affects its internal margins. This lets per-facet draws reuse the
+ * same projection scale and lets shared ticks line up with the
+ * interior cell boundaries exactly.
+ *
+ * Axis modes — see {@link AxisMode}:
+ *   - `"outer"` → outer band rect is populated; per-cell gutter is 0.
+ *   - `"cell"` → outer band is undefined; each cell owns its own gutter.
+ *   - `"none"` → no gutter anywhere on that side; used by axis-less
+ *     chart types.
+ *
+ * Because all cells are identical in size, callers can sample *any*
+ * cell's layout (e.g. `cells[0].layout`) for tick / scale
+ * computations.
+ */
+export declare function buildFacetGrid(labels: string[], opts: FacetGridOptions): FacetGrid;

package/dist/esm/layout/plot-layout.d.ts

@@ -0,0 +1,104 @@
+export interface PlotMargins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export interface PlotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PlotLayoutOptions {
+    hasXLabel: boolean;
+    hasYLabel: boolean;
+    hasLegend: boolean;
+    /**
+     * Additional CSS-pixel height reserved at the bottom of the plot for a
+     * hierarchical / rotated categorical X axis. Overrides the default 24px
+     * tick band. The axis-label allowance from `hasXLabel` is preserved.
+     */
+    bottomExtra?: number;
+    /**
+     * Total CSS-pixel width reserved at the left of the plot for a
+     * hierarchical categorical Y axis. Overrides the default `55 +
+     * hasYLabel*16` left gutter. The axis-label allowance from `hasYLabel`
+     * is preserved.
+     */
+    leftExtra?: number;
+    /**
+     * Total CSS-pixel width reserved at the right of the plot. Overrides
+     * the default (`80` when `hasLegend`, else `16`). Faceted cells
+     * without axes (treemap / sunburst in grid mode) pass `0` to make
+     * adjacent cell plot rects flush; axis-bearing charts leave it
+     * unset to keep the default breathing-room margin.
+     */
+    rightExtra?: number;
+    /**
+     * Absolute canvas-coordinate offset for this layout's plot origin.
+     * When set, `cssWidth` / `cssHeight` describe the *outer* canvas, and
+     * `originX` / `originY` name the top-left corner of the cell this
+     * layout represents. The cell's own width/height come from
+     * `cellWidth` / `cellHeight`. `margins` are computed relative to the
+     * cell then shifted into canvas-absolute space so projection
+     * matrices, scissor, and `dataToPixel` all operate in full-canvas
+     * coordinates without branching per-facet.
+     *
+     * When any of these fields is unset, the layout is single-plot: the
+     * cell occupies the whole canvas and `originX` / `originY` default
+     * to 0.
+     */
+    originX?: number;
+    originY?: number;
+    cellWidth?: number;
+    cellHeight?: number;
+}
+/**
+ * Coordinates margins and coordinate transforms between WebGL and Canvas2D.
+ * All measurements are in CSS pixels (not physical/DPR-scaled pixels).
+ */
+export declare class PlotLayout {
+    readonly margins: PlotMargins;
+    readonly plotRect: PlotRect;
+    readonly cssWidth: number;
+    readonly cssHeight: number;
+    paddedXMin: number;
+    paddedXMax: number;
+    paddedYMin: number;
+    paddedYMax: number;
+    constructor(cssWidth: number, cssHeight: number, options: PlotLayoutOptions);
+    /**
+     * Build an orthographic projection matrix that maps data coordinates
+     * [xMin..xMax, yMin..yMax] to the plot area sub-region of clip space [-1, 1].
+     *
+     * The matrix bakes margin offsets into the transform so that gl.viewport
+     * remains full-canvas and no scissor/sub-viewport is needed.
+     *
+     * `clamp`, when set, names the axis that carries the *value* (as
+     * opposed to categorical / positional) data. Today it only affects
+     * `requireZero`; both axes always receive symmetric `padRatio` padding.
+     *
+     * `requireZero`, when true, guarantees that the unpadded value `0`
+     * falls inside the clamped axis's final domain. For all-positive
+     * data the axis minimum is pinned at `0` (the baseline sits on the
+     * axis line); for all-negative data the maximum is pinned at `0`;
+     * for data that already straddles zero, nothing changes. Pairs with
+     * `clamp`, and is a no-op when `clamp` is unset.
+     *
+     * `padRatio` controls the symmetric cosmetic pad on both axes
+     * (default 2%). Charts that want plot edges flush with the axes
+     * (e.g. heatmap, whose cell rects already span the exact domain)
+     * pass `0`.
+     */
+    buildProjectionMatrix(xMin: number, xMax: number, yMin: number, yMax: number, clamp?: "x" | "y", requireZero?: boolean, padRatio?: number, xOrigin?: number, yOrigin?: number): Float32Array;
+    /**
+     * Convert data coordinates to CSS pixel coordinates on the overlay canvas.
+     * Uses the padded domain from the last `buildProjectionMatrix` call so
+     * that pixel positions align exactly with the WebGL projection.
+     */
+    dataToPixel(dataX: number, dataY: number): {
+        px: number;
+        py: number;
+    };
+}

package/dist/esm/layout/ticks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generate an array of "nice" tick values spanning [min, max].
+ * @param min - Domain minimum
+ * @param max - Domain maximum
+ * @param targetCount - Desired number of ticks (approximate)
+ */
+export declare function computeNiceTicks(min: number, max: number, targetCount: number): number[];
+/**
+ * Format a numeric tick value for display.
+ * Uses K/M/B suffixes for large numbers, fixed decimals for small.
+ */
+export declare function formatTickValue(val: number): string;
+/**
+ * Format a timestamp (ms since epoch) as a human-readable date/time label.
+ * Adapts precision based on the tick spacing.
+ */
+export declare function formatDateTickValue(val: number, stepMs?: number): string;

package/dist/esm/map/mercator.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Web Mercator projection helpers and XYZ tile-pyramid math. Pure
+ * functions, no side effects, safe to call from any thread (including
+ * the renderer worker).
+ *
+ * Mercator output is in *meters*, not the normalized [0, 1] form that
+ * some libraries use. We feed the meter values straight into the
+ * cartesian projection matrix in `plot-layout.ts`, so the upstream
+ * domain stays in physical units and per-pixel ground resolution is a
+ * straightforward division.
+ */
+/**
+ * WGS84 equatorial radius in meters. Matches what every standard tile
+ * provider (OSM, CartoDB, Mapbox, ...) uses for Web Mercator.
+ */
+export declare const EARTH_RADIUS_M = 6378137;
+/**
+ * Half the world extent in Mercator meters: π · R ≈ 20037508.34. The
+ * full Mercator square is `[-WORLD_HALF, +WORLD_HALF]` on both axes.
+ */
+export declare const WORLD_HALF: number;
+/**
+ * Maximum absolute latitude representable in Web Mercator. Beyond this
+ * the projection diverges to ±∞; tile providers don't ship tiles
+ * outside [-MAX_LAT, +MAX_LAT]. Computed as
+ * `atan(sinh(π)) · 180 / π ≈ 85.0511287798°`.
+ */
+export declare const MAX_LAT = 85.0511287798066;
+/**
+ * Project (longitude, latitude) in degrees to Web Mercator meters.
+ *
+ * Latitudes outside ±MAX_LAT return `[NaN, NaN]` so callers in the
+ * cartesian build path (which already has a post-`projectPoint` NaN
+ * guard) discard those rows without special-casing.
+ */
+export declare function lonLatToMercator(lon: number, lat: number): [number, number];
+/**
+ * Inverse: Mercator meters → (lon, lat) in degrees. Used by tooltip
+ * formatting and any UI that surfaces the cursor position to the user.
+ */
+export declare function mercatorToLonLat(x: number, y: number): [number, number];
+/**
+ * A single XYZ tile address.
+ */
+export interface TileId {
+    z: number;
+    x: number;
+    y: number;
+}
+/**
+ * Mercator extent in meters of one XYZ tile. Y is in the Mercator
+ * convention (north positive), not the tile-pyramid convention (y=0
+ * at the top); the conversion is done inside the helper.
+ */
+export interface TileExtent {
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+}
+/**
+ * Return the Mercator-meter bounds of an XYZ tile. Tile (0, 0) at
+ * zoom 0 covers `[-WORLD_HALF, +WORLD_HALF]` on both axes — the whole
+ * world. Each zoom level subdivides into `2^z × 2^z` equal squares.
+ */
+export declare function tileExtent(z: number, x: number, y: number): TileExtent;
+/**
+ * Pick the integer zoom level whose tile pixel resolution best matches
+ * the requested Mercator-meters-per-pixel. Snaps to the next coarser
+ * level so we never undersample (a finer level would fetch tiles only
+ * to scale them down).
+ *
+ * `targetResolutionMpp` is meters per *device pixel*; the caller
+ * computes it as `(domain.xMax - domain.xMin) / plotRect.width`.
+ */
+export declare function pickZoom(targetResolutionMpp: number, tileSizePx?: number, maxZoom?: number): number;
+/**
+ * Enumerate every visible tile at a single zoom level that intersects
+ * the given Mercator extent. Returned in left-to-right, top-to-bottom
+ * order so the layer's render loop produces a deterministic draw
+ * sequence (helps with debugging tile-load races).
+ *
+ * Tiles outside the world's `[0, 2^z)` X range are *not* wrapped —
+ * antimeridian wraparound is a v2 feature. Callers see a gap when
+ * panning past ±180° lon; tiles inside the valid range still render.
+ */
+export declare function tilesForExtent(extent: TileExtent, z: number): TileId[];
+/**
+ * Return the parent tile (one zoom level coarser) of the given tile,
+ * along with the [0, 1] UV sub-rect that this tile occupies inside
+ * its parent. Used by the layer's "draw what we have" fallback while
+ * a missing target tile is in-flight — the parent texture is sampled
+ * with the sub-rect so the visible region keeps tile-aligned content
+ * instead of flashing blank.
+ *
+ * Returns `null` for zoom-0 tiles (no parent).
+ */
+export declare function parentTile(tile: TileId): {
+    parent: TileId;
+    uvMin: [number, number];
+    uvMax: [number, number];
+} | null;

package/dist/esm/map/tile-cache.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Bounded LRU of `WebGLTexture` keyed by tile cache key (see
+ * `tile-loader.tileKey`). Evicts least-recently-touched entries on
+ * insert past `capacity`, deleting their GPU textures.
+ *
+ * Default capacity of 256 is enough to cover a full screen worth of
+ * tiles at zoom-1 jumps either side of the current viewport plus the
+ * parent fallbacks — at 256×256 RGBA that's ~64 MB of texture memory,
+ * which sits comfortably under the 256 MB headroom most browsers
+ * grant to a tab.
+ */
+export declare class TileCache {
+    private _entries;
+    private readonly _capacity;
+    constructor(capacity?: number);
+    /**
+     * Fetch a texture by key. Touching an existing entry moves it to
+     * the LRU tail so it survives the next eviction sweep.
+     */
+    get(key: string): WebGLTexture | undefined;
+    /**
+     * Insert a texture under `key`. If the cache is at capacity, evict
+     * the oldest entry first (calling `gl.deleteTexture` on its GPU
+     * resource).
+     */
+    set(gl: WebGL2RenderingContext | WebGLRenderingContext, key: string, texture: WebGLTexture): void;
+    /**
+     * Whether a key is resident. Used to gate the "kick off a fetch"
+     * branch in the layer's render loop.
+     */
+    has(key: string): boolean;
+    /**
+     * Release every texture. Called on chart destroy. Safe to call
+     * with a stale `gl` reference (no-op if `deleteTexture` rejects),
+     * but in practice the caller passes the still-live worker context.
+     */
+    dispose(gl: WebGL2RenderingContext | WebGLRenderingContext): void;
+}

package/dist/esm/map/tile-layer.d.ts

@@ -0,0 +1,66 @@
+import type { WebGLContextManager } from "../webgl/context-manager";
+import type { PlotLayout } from "../layout/plot-layout";
+import type { TileSource } from "./tile-source";
+type GL = WebGL2RenderingContext | WebGLRenderingContext;
+/**
+ * Renders an XYZ raster tile basemap into the chart's webgl canvas
+ * inside the plot rect's scissor. Used by `MapChart` from inside
+ * `renderInPlotFrame`, before the glyph draw, so chart glyphs (point,
+ * line, density) composite naturally on top of the basemap.
+ *
+ * The layer owns:
+ *   - The tile shader program (compiled once per WebGL context).
+ *   - A unit-quad corner buffer (one 2-byte attribute, reused per
+ *     tile).
+ *   - A `TileCache` (LRU of `WebGLTexture`).
+ *   - A `TileLoader` (async fetch + dedup).
+ *
+ * On each render: pick the integer zoom that matches the requested
+ * meters-per-pixel, enumerate visible tiles at that zoom, and draw
+ * each one — either with the loaded texture or with a parent
+ * texture's sub-rect while the target is in flight.
+ */
+export declare class TileLayer {
+    private _program;
+    private _cornerBuffer;
+    private _cache;
+    private _loader;
+    private _source;
+    private _alpha;
+    private _onTileLoad;
+    /**
+     * Hook the "tile arrived" notification through to the chart's
+     * render scheduler. Called once when the layer is constructed
+     * by `MapChart`.
+     */
+    setOnTileLoad(cb: () => void): void;
+    /**
+     * Swap the tile source (e.g. light ↔ dark theme). Drops the cache
+     * because the cached textures came from the prior source's URLs.
+     */
+    setSource(gl: GL, source: TileSource): void;
+    setAlpha(alpha: number): void;
+    get source(): TileSource | null;
+    /**
+     * Render the basemap for the current visible Mercator extent.
+     * Caller is responsible for binding the chart's main framebuffer
+     * (the plot-frame scissor is already in place by the time we get
+     * here). The same `projection` matrix the glyph draw uses is
+     * passed straight through.
+     */
+    render(glManager: WebGLContextManager, layout: PlotLayout, projection: Float32Array, domain: {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    }, xOrigin: number, yOrigin: number): void;
+    /**
+     * Free every GPU resource. Called from `MapChart.destroyInternal`.
+     */
+    destroy(gl: GL): void;
+    private _drawTile;
+    private _issueDraw;
+    private _kickLoad;
+    private _ensureProgram;
+}
+export {};

package/dist/esm/map/tile-loader.d.ts

@@ -0,0 +1,52 @@
+import type { TileSource } from "./tile-source";
+/**
+ * Async tile fetcher with in-flight dedup and abort-on-zoom-change.
+ *
+ * Runs inside the renderer worker (the chart's host process). `fetch`
+ * and `createImageBitmap` are both available in workers, and the
+ * resulting `ImageBitmap` can be uploaded straight to a WebGL2 texture
+ * via `gl.texImage2D(..., ImageBitmap)` — no main-thread bounce.
+ *
+ * The loader does not own GPU resources. Upload to texture happens in
+ * the tile layer once an `ImageBitmap` resolves; the layer then drops
+ * the bitmap (calling `close()` to free the decoded pixels).
+ */
+export declare class TileLoader {
+    private _inFlight;
+    private _onLoad;
+    /**
+     * Register the "tile arrived" callback. The layer wires this to
+     * `chart.requestRender(glManager)` so a newly-loaded tile triggers
+     * exactly one extra frame.
+     */
+    setOnLoad(cb: () => void): void;
+    /**
+     * Kick off a fetch (or return the in-flight one). The same
+     * (source.id, z, x, y) tuple only ever has one outstanding
+     * fetch; multiple callers share the result. Rejected fetches
+     * (network error, abort) resolve to `null` so callers can skip
+     * the tile without try/catch noise on every miss.
+     */
+    load(source: TileSource, z: number, x: number, y: number): Promise<ImageBitmap | null>;
+    /**
+     * Abort every in-flight fetch. Called on view teardown / chart
+     * destroy. Fetches whose `Response` has already arrived but
+     * haven't yet decoded will still complete the decode and resolve
+     * to `null` (because `_onLoad` is replaced or the cache is gone)
+     * — harmless, no resource leak.
+     */
+    cancelAll(): void;
+    /**
+     * Abort just the fetches whose key isn't in the supplied set.
+     * The layer calls this on every render with the currently-visible
+     * tile set so old-zoom requests don't keep arriving and triggering
+     * spurious re-renders after the user has moved on.
+     */
+    cancelExcept(liveKeys: Set<string>): void;
+    private _fetchAndDecode;
+}
+/**
+ * Stable cache key for a tile under a given source. Embedded source id
+ * so swapping sources (light/dark) doesn't surface stale tiles.
+ */
+export declare function tileKey(sourceId: string, z: number, x: number, y: number): string;

package/dist/esm/map/tile-source.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A tile source describes *where* to fetch raster XYZ tiles and what
+ * attribution text the renderer must display in the chrome canvas.
+ * Implementations are stateless — the tile loader handles caching and
+ * in-flight dedup.
+ */
+export interface TileSource {
+    /**
+     * Build the URL for tile (z, x, y). Implementations typically
+     * substitute a template like `{z}/{x}/{y}` and may rotate
+     * subdomains for browsers that throttle concurrent connections
+     * per host.
+     */
+    urlFor(z: number, x: number, y: number): string;
+    /**
+     * Plain-text attribution shown in the bottom-right of the chrome
+     * canvas. Required by every major tile provider's terms of use —
+     * do not suppress it without provider-side opt-out.
+     */
+    readonly attribution: string;
+    /**
+     * Side length of one tile in pixels. Tile providers ship 256 by
+     * default; a few offer 512 (`@2x`) variants. Used by the zoom-
+     * level picker to convert meters-per-pixel into a zoom level.
+     */
+    readonly tileSize: number;
+    /**
+     * Maximum zoom level the provider serves. Tiles requested above
+     * this fall back to the deepest available level with sub-tile
+     * UVs — same trick used during async loads.
+     */
+    readonly maxZoom: number;
+    /**
+     * Stable identifier for caching. Two `TileSource` instances with
+     * the same `id` share a tile cache; switching source (e.g. theme
+     * change) invalidates and re-fetches.
+     */
+    readonly id: string;
+}
+/**
+ * Subdomain-rotated URL template. Replaces `{s}` with one of the
+ * provided subdomains hashed by `(x + y)`, and `{z}`, `{x}`, `{y}`
+ * with the tile address. Most major tile providers fit this shape.
+ */
+export declare class TemplatedTileSource implements TileSource {
+    readonly id: string;
+    private readonly template;
+    readonly attribution: string;
+    readonly tileSize: number;
+    readonly maxZoom: number;
+    private readonly subdomains;
+    constructor(id: string, template: string, attribution: string, tileSize?: number, maxZoom?: number, subdomains?: readonly string[]);
+    urlFor(z: number, x: number, y: number): string;
+}
+/**
+ * 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.
+ */
+export type TileProviderId = "carto-positron" | "carto-dark-matter" | "carto-voyager";
+/**
+ * Resolve a `TileProviderId` (from PluginConfig) to a concrete
+ * `TileSource`. Unknown ids fall back to Positron so a misconfigured
+ * `_pluginConfig` never produces a blank map.
+ */
+export declare function tileSourceFor(id: TileProviderId | string): TileSource;