@perspective-dev/viewer-charts 5.3.0 → 5.4.0

package/dist/esm/axis/legend.d.ts

@@ -1,7 +1,55 @@
-import type { Canvas2D } from "../charts/canvas-types";
+import type { Canvas2D, Context2D } from "../charts/canvas-types";
 import type { PlotLayout, PlotRect } from "../layout/plot-layout";
+import { LEGEND_LINE_HEIGHT, type LegendAutoFit, type LegendController } from "../interaction/legend-controller";
 import { type GradientStop } from "../theme/gradient";
 import type { Theme } from "../theme/theme";
+export { LEGEND_LINE_HEIGHT };
+/**
+ * Presentation context threaded into every legend painter. Carries the
+ * resolved `legend_mode` branch and the chart's {@link LegendController}
+ * — the painter reads its scroll offset and reports the painted
+ * geometry back so hit-testing always resolves against what is on
+ * screen. `"none"` mode never reaches a painter (call sites skip and
+ * `clearPainted()` instead).
+ */
+export interface LegendPaintView {
+    mode: "sidebar" | "floating";
+    legend: LegendController;
+    title?: string;
+    sidebarGutter?: number;
+    /**
+     * Floating background-fill opacity (`plugin_config.legend_opacity`,
+     * default 1). Border, header text, and entries stay opaque.
+     */
+    opacity?: number;
+}
+export declare function legendAutoFit(canvas: Canvas2D | null | undefined, theme: Theme, entryCount: number, labels: () => Iterable<string>, opts?: {
+    title?: string;
+    leading?: number;
+    fontPx?: number;
+}): LegendAutoFit;
+export declare function gradientLegendAutoFit(canvas: Canvas2D | null | undefined, theme: Theme, colorDomain: {
+    min: number;
+    max: number;
+}, formatter?: (v: number) => string, title?: string): LegendAutoFit;
+/**
+ * Paint the floating panel's chrome — themed background, border, and
+ * header strip — and return the content rect inside it. The header
+ * carries `title` and doubles as the move grip. `opacity` applies to
+ * the background fill only.
+ */
+export declare function paintFloatingLegendFrame(ctx: Context2D, box: PlotRect, theme: Theme, title: string | undefined, opacity?: number): PlotRect;
+/**
+ * Paint the scroll thumb on the content rect's right edge. No-op when
+ * the content fits.
+ */
+export declare function paintLegendScrollbar(ctx: Context2D, content: PlotRect, scroll: number, contentHeight: number, theme: Theme): void;
+/**
+ * Clip `text` to `maxWidth` with a trailing ellipsis. Only called for
+ * entries inside the visible window, so the `measureText` cost is
+ * bounded by the box height, not the entry count.
+ */
+export declare function truncateText(ctx: Context2D, text: string, maxWidth: number): string;
 /**
  * Render a vertical color gradient legend on the Canvas2D overlay.
  * Only call when a color column is active. When `colorDomain` crosses
@@ -15,7 +63,7 @@ export declare function renderLegend(canvas: Canvas2D, layout: PlotLayout, color
     min: number;
     max: number;
     label: string;
-}, stops: GradientStop[], theme: Theme, formatter?: (v: number) => string): void;
+}, stops: GradientStop[], theme: Theme, formatter?: (v: number) => string, view?: LegendPaintView): void;
 /**
  * Render a gradient legend at an explicit canvas-absolute rect.
  * Used by facet grids that paint one legend for the whole grid and
@@ -25,7 +73,7 @@ export declare function renderLegendAt(canvas: Canvas2D, rect: PlotRect, colorDo
     min: number;
     max: number;
     label: string;
-}, stops: GradientStop[], theme: Theme, formatter?: (v: number) => string): void;
+}, stops: GradientStop[], theme: Theme, formatter?: (v: number) => string, view?: LegendPaintView): void;
 /**
  * Render a categorical legend with discrete colored swatches.
  * Used when split_by or string color columns produce distinct categories.
@@ -35,10 +83,10 @@ export declare function renderLegendAt(canvas: Canvas2D, rect: PlotRect, colorDo
  * shared legend pass an explicit rect to `renderCategoricalLegendAt`
  * directly.
  */
-export declare function renderCategoricalLegend(canvas: Canvas2D, layout: PlotLayout, labels: Map<string, number>, palette: [number, number, number][], theme: Theme): void;
+export declare function renderCategoricalLegend(canvas: Canvas2D, layout: PlotLayout, labels: Map<string, number>, palette: [number, number, number][], theme: Theme, view?: LegendPaintView): void;
 /**
  * Render a categorical legend at an explicit canvas-absolute rect.
  * Used by facet grids that paint one legend for the whole grid and by
  * single-plot charts through {@link renderCategoricalLegend}.
  */
-export declare function renderCategoricalLegendAt(canvas: Canvas2D, rect: PlotRect, labels: Map<string, number>, palette: [number, number, number][], theme: Theme): void;
+export declare function renderCategoricalLegendAt(canvas: Canvas2D, rect: PlotRect, labels: Map<string, number>, palette: [number, number, number][], theme: Theme, view?: LegendPaintView): void;

package/dist/esm/axis/map-ticks.d.ts

@@ -0,0 +1,15 @@
+import type { PlotLayout } from "../layout/plot-layout";
+export interface MapDegreeTicks {
+    xTicks: number[];
+    yTicks: number[];
+    formatX: (meters: number) => string;
+    formatY: (meters: number) => string;
+}
+/**
+ * Compute "nice" longitude/latitude ticks for the visible window of a
+ * map layout. Must be called AFTER `buildProjectionMatrix` has seeded
+ * the layout's padded-domain fields — the ticks are derived from the
+ * exact meter domain the projection maps, or labels would misalign
+ * with glyphs.
+ */
+export declare function computeMapDegreeTicks(layout: PlotLayout): MapDegreeTicks;

package/dist/esm/charts/candlestick/candlestick-interact.d.ts

@@ -2,9 +2,5 @@ import type { CandlestickChart } from "./candlestick";
 export declare function handleCandlestickHover(chart: CandlestickChart, mx: number, my: number): void;
 export declare function showCandlestickPinnedTooltip(chart: CandlestickChart, idx: number): void;
 export declare function dismissCandlestickPinnedTooltip(chart: CandlestickChart): void;
-/**
- * Build tooltip lines for candle at index `idx` in the columnar
- * storage. Indexed access avoids materializing a `CandleRecord` POJO
- * on the hot tooltip path.
- */
-export declare function buildCandlestickTooltipLines(chart: CandlestickChart, idx: number): string[];
+export declare function buildCandlestickTooltipLines(chart: CandlestickChart, idx: number): string[][];
+export declare function candleCategoryText(chart: CandlestickChart, catIdx: number): string;

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

@@ -30,6 +30,12 @@ export declare class CartesianChart extends AbstractChart {
     readonly glyph: Glyph;
     constructor(glyph: Glyph);
     protected colorScaleColumn(): string | null;
+    /**
+     * Chrome-only repaint for legend scroll / floating-legend drag —
+     * the same lightweight path hover updates use. No GL pass; the
+     * composite re-presents over the retained plot bitmap.
+     */
+    repaintChrome(): void;
     /**
      * Rendering pipeline selector. `"cartesian"` is the default —
      * draws axes, gridlines, and ticks via the chrome canvas.

package/dist/esm/charts/cartesian/glyph.d.ts

@@ -38,13 +38,14 @@ export interface Glyph {
      * Glyphs whose tooltip is geometry-only (e.g. `LineGlyph`) return
      * a microtask-resolved promise.
      */
-    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[]>;
+    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[][]>;
     /**
      * Hover-overlay options (crosshair, highlight radius).
      */
     tooltipOptions(): {
         crosshair: boolean;
         highlightRadius: number;
+        axisIndicators: boolean;
     };
     /**
      * Release GL resources created by `ensureProgram`.

package/dist/esm/charts/cartesian/glyphs/density.d.ts

@@ -26,10 +26,11 @@ export declare class DensityGlyph implements Glyph {
     ensureProgram(chart: CartesianChart, glManager: WebGLContextManager): void;
     draw(chart: CartesianChart, glManager: WebGLContextManager, projection: Float32Array): void;
     drawSeries(chart: CartesianChart, glManager: WebGLContextManager, projection: Float32Array, seriesIdx: number): void;
-    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[]>;
+    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[][]>;
     tooltipOptions(): {
         crosshair: boolean;
         highlightRadius: number;
+        axisIndicators: boolean;
     };
     destroy(chart: CartesianChart): void;
     /**

package/dist/esm/charts/cartesian/glyphs/lines.d.ts

@@ -14,10 +14,11 @@ export declare class LineGlyph implements Glyph {
     ensureProgram(_chart: CartesianChart, glManager: WebGLContextManager): void;
     draw(chart: CartesianChart, glManager: WebGLContextManager, projection: Float32Array): void;
     drawSeries(chart: CartesianChart, glManager: WebGLContextManager, projection: Float32Array, seriesIdx: number): void;
-    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[]>;
+    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[][]>;
     tooltipOptions(): {
         crosshair: boolean;
         highlightRadius: number;
+        axisIndicators: boolean;
     };
     destroy(chart: CartesianChart): void;
 }

package/dist/esm/charts/cartesian/glyphs/points.d.ts

@@ -15,10 +15,11 @@ export declare class PointGlyph implements Glyph {
     ensureProgram(_chart: CartesianChart, glManager: WebGLContextManager): void;
     draw(chart: CartesianChart, glManager: WebGLContextManager, projection: Float32Array): void;
     drawSeries(chart: CartesianChart, glManager: WebGLContextManager, projection: Float32Array, seriesIdx: number): void;
-    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[]>;
+    buildTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[][]>;
     tooltipOptions(): {
         crosshair: boolean;
         highlightRadius: number;
+        axisIndicators: boolean;
     };
     destroy(_chart: CartesianChart): void;
 }

package/dist/esm/charts/cartesian/tooltip-lines.d.ts

@@ -8,4 +8,4 @@ import type { CartesianChart } from "./cartesian";
  * Returns `[]` when the chart has no row-index mirror or no fetcher;
  * callers should fall back to a geometry-only tooltip in that case.
  */
-export declare function buildPointRowTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[]>;
+export declare function buildPointRowTooltipLines(chart: CartesianChart, flatIdx: number): Promise<string[][]>;

package/dist/esm/charts/chart-base.d.ts

@@ -5,6 +5,7 @@ import type { WebGLContextManager } from "../webgl/context-manager";
 import { ZoomController, type ZoomConfig } from "../interaction/zoom-controller";
 import { type ChartImplementation, type FacetConfig, type PluginConfig } from "./chart";
 import { TooltipController, type HostSink, type TooltipCallbacks } from "../interaction/tooltip-controller";
+import { LegendController } from "../interaction/legend-controller";
 import type { PerspectiveClickDetail } from "../event-detail";
 import type { ViewConfig } from "@perspective-dev/client";
 import { type Theme } from "../theme/theme";
@@ -144,6 +145,7 @@ export declare abstract class AbstractChart implements ChartImplementation {
      * the pre-refactor output.
      */
     _pluginConfig: PluginConfig;
+    _legend: LegendController;
     _tooltip: TooltipController;
     /**
      * Reference to the active host sink, captured in {@link attachTooltip}.

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

@@ -158,6 +158,7 @@ export interface ChartImplementation {
      * host's filter set.
      */
     deselect?(): void;
+    repaintChrome?(): void;
     destroy(): void;
 }
 export interface FacetConfig {
@@ -360,13 +361,15 @@ export interface PluginConfig {
      */
     gradient_color_mode: "mean" | "density" | "extreme" | "signed";
     /**
-     * Map basemap tile provider. Applies only to map plugin tags
-     * (`map-scatter`, `map-line`, `map-density`). Cartesian charts
-     * ignore the field. Surfaced as an enum on the settings panel so
-     * users can switch light/dark/voyager without writing custom
-     * tile-source code.
+     * Map basemap tile provider — a `TileSourceSpec` id from the
+     * tile-source registry ([map/tile-sources.json] entries plus any
+     * runtime `registerTileSource` additions). Applies only to map
+     * plugin tags (`map-scatter`, `map-line`, `map-density`); other
+     * charts ignore the field. The default is the JSON's FIRST entry
+     * (reordering the file changes the default), and unknown ids fall
+     * back to that same entry rather than blanking the map.
      */
-    map_tile_provider: "carto-positron" | "carto-dark-matter" | "carto-voyager";
+    map_tile_provider: string;
     /**
      * Map basemap alpha (0..1). Pre-multiplied into the tile fragment
      * shader's output so the chart's glyph layer composites over a
@@ -374,5 +377,73 @@ export interface PluginConfig {
      * shows the tiles at full opacity.
      */
     map_tile_alpha: number;
+    /**
+     * Map plugins only. `true` (default): standard numeric axes in the
+     * usual cartesian gutters, with tick labels in degrees
+     * longitude/latitude (`122.4°W`) rather than Mercator meters.
+     * `false`: no axes, and the plot is full-bleed — the basemap fills
+     * the entire canvas, minus only the sidebar legend gutter when a
+     * legend is actually shown. Gridlines are never drawn in map mode
+     * — the gridline canvas composites BELOW the GL layer, so opaque
+     * basemap tiles would hide them.
+     */
+    numeric_axes: boolean;
+    /**
+     * Legend presentation mode. `"auto"` (default) resolves per frame
+     * to `"floating"` when every entry fits the default floating panel
+     * without scrolling (≤ 7 entries; continuous gradient legends
+     * always qualify) and to `"sidebar"` otherwise — see
+     * `resolveLegendMode`. Treemap overrides the default to
+     * `"sidebar"` (a floating panel over edge-to-edge tiles always
+     * occludes data).
+     */
+    legend_mode: "auto" | "sidebar" | "none" | "floating";
+    /**
+     * Floating-panel sizing regime. `"auto"` (default) sizes the panel
+     * to its CONTENT every frame — the height hugs the entry rows
+     * exactly, and the width hugs the widest entry label (measured on
+     * the chrome canvas). `"fixed"` uses the saved `legend_width_px` /
+     * `legend_height_px` verbatim.
+     *
+     * Applies to `legend_mode: "floating"` ONLY; the sidebar gutter is
+     * always `legend_width_px` (its height is the plot's). Dragging a
+     * resize handle switches an auto panel to `"fixed"` — otherwise
+     * the gesture would be undone by the next paint — and
+     * double-clicking a resize handle switches it back.
+     */
+    legend_size_mode: LegendSizeMode;
+    /**
+     * Legend width in CSS pixels. `0` (default) = automatic — each
+     * chart family keeps its historical gutter width (80–96px). In
+     * `"sidebar"` mode this is the full right-gutter width; in
+     * `"floating"` mode it is the panel width. Clamped at paint time
+     * to at most half the canvas width so a saved wide legend cannot
+     * crush a small panel. Ignored by a floating panel in
+     * `legend_size_mode: "auto"`.
+     */
+    legend_width_px: number;
+    /**
+     * Floating-legend panel height in CSS pixels. Ignored in
+     * `"sidebar"` mode (the legend spans the plot height) and by a
+     * floating panel in `legend_size_mode: "auto"`. Clamped at paint
+     * time to the canvas height.
+     */
+    legend_height_px: number;
+    /**
+     * Canvas corner that `legend_x` / `legend_y` are measured FROM.
+     * Floating mode only. The panel keeps its distance to this corner
+     * across panel resizes — anchor `"bottom-right"` with small
+     * offsets stays glued to the bottom-right.
+     */
+    legend_anchor: LegendAnchor;
+    legend_x: number;
+    legend_y: number;
+    legend_opacity: number;
+    /** Per-column width cap for tooltip grid cells, in CSS pixels. */
+    tooltip_max_column_px: number;
+    /** Tooltip background/border alpha (0..1). */
+    tooltip_opacity: number;
 }
+export type LegendAnchor = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+export type LegendSizeMode = "auto" | "fixed";
 export declare const DEFAULT_PLUGIN_CONFIG: PluginConfig;

package/dist/esm/charts/common/draw-tooltip-box.d.ts

@@ -1,9 +1,10 @@
 import type { Context2D } from "../canvas-types";
 import type { Theme } from "../../theme/theme";
+import { type TooltipContent, type TooltipStyle } from "../../interaction/tooltip-grid";
 /**
  * Draw a freestanding tooltip box anchored near (cx, cy), measuring
  * lines, sizing/clamping the box, painting bg/border, and laying out
  * text rows. Shared by sunburst + treemap which need a non-PlotLayout
  * anchor.
  */
-export declare function drawTooltipBox(ctx: Context2D, theme: Theme, lines: string[], cx: number, cy: number, cssWidth: number, cssHeight: number, fontFamily: string): void;
+export declare function drawTooltipBox(ctx: Context2D, theme: Theme, grid: TooltipContent, cx: number, cy: number, cssWidth: number, cssHeight: number, fontFamily: string, style?: TooltipStyle): void;

package/dist/esm/charts/common/tree-interact.d.ts

@@ -26,7 +26,7 @@ export declare function emitTreeNodeEvent(chart: TreeInteractChart, nodeId: numb
  * fetch; branch nodes have no underlying row so they emit a Children
  * count instead.
  */
-export declare function buildTreeTooltipLines(chart: TreeInteractChart, nodeId: number): Promise<string[]>;
+export declare function buildTreeTooltipLines(chart: TreeInteractChart, nodeId: number): Promise<string[][]>;
 /**
  * Pin a tooltip at the chart-supplied anchor. Lines are fetched lazily;
  * the `_pinnedNodeId` check on resolve discards stale results from a

package/dist/esm/charts/series/series-build.d.ts

@@ -213,6 +213,13 @@ export interface SeriesPipelineResult {
      * is the position. Indexed by `catIdx` (0..numCategories-1).
      */
     categoryPositions: Float64Array | null;
+    /**
+     * One entry per (aggregate × split), in `k * P + p` order. INVARIANT:
+     * `series.length === aggregates.length * splitPrefixes.length` —
+     * consumers index `series[k * P]` directly (glyph runs, the
+     * `domain_mode: "expand"` axis signature), so an empty `series` MUST
+     * be paired with empty `aggregates` / `splitPrefixes`.
+     */
     series: SeriesInfo[];
     /**
      * Columnar bar/area records, one per (catIdx, agg, split) for series

package/dist/esm/charts/series/series-interact.d.ts

@@ -32,7 +32,7 @@ export declare function handleBarLegendClick(chart: SeriesChart, mx: number, my:
 /**
  * Build the per-bar tooltip content lines.
  */
-export declare function buildBarTooltipLines(chart: SeriesChart, b: SeriesChartRecord): string[];
+export declare function buildBarTooltipLines(chart: SeriesChart, b: SeriesChartRecord): string[][];
 /**
  * Format the hierarchical path label for a given category index. Used by
  * the tooltip — the axis uses per-level text directly instead.

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

@@ -74,6 +74,12 @@ export declare class SeriesChart extends CategoricalYChart {
      * always present. The value axis stays freely zoomable.
      */
     protected getZoomConfig(): ZoomConfig;
+    /**
+     * Chrome-only repaint for legend scroll / floating-legend drag —
+     * the same lightweight path hover updates use. No GL pass; the
+     * composite re-presents over the retained plot bitmap.
+     */
+    repaintChrome(): void;
     _locations: CachedLocations | null;
     _aggregates: string[];
     _splitPrefixes: string[];

package/dist/esm/index.d.ts

@@ -1,3 +1,5 @@
 export type { PerspectiveClickDetail } from "./event-detail";
 export { PerspectiveSelectDetail } from "./event-detail";
+export { registerTileSource } from "./plugin/plugin";
+export { tileSources, type TileSourceSpec } from "./map/tile-source";
 export declare function register(...plugin_names: string[]): void;

package/dist/esm/interaction/axis-indicators.d.ts

@@ -0,0 +1,11 @@
+import type { Canvas2D } from "../charts/canvas-types";
+import type { PlotLayout } from "../layout/plot-layout";
+import type { Theme } from "../theme/theme";
+export type AxisSide = "bottom" | "left" | "right";
+export interface AxisIndicator {
+    side: AxisSide;
+    px: number;
+    py: number;
+    text: string;
+}
+export declare function renderAxisHoverIndicators(canvas: Canvas2D | null, layout: PlotLayout, theme: Theme, dpr: number, indicators: AxisIndicator[], opacity?: number): void;

package/dist/esm/interaction/host-sink-dom.d.ts

@@ -1,4 +1,5 @@
 import type { CssBounds, HostSink } from "./tooltip-controller";
+import { type TooltipContent, type TooltipStyle } from "./tooltip-grid";
 /**
  * Host-side `HostSink` that materializes pinned tooltips as a `<div>`
  * next to the GL canvas, and applies cursor changes to the canvas's
@@ -10,10 +11,10 @@ export declare class DomHostSink implements HostSink {
     private _parent;
     private _div;
     constructor(glCanvas: HTMLCanvasElement, parent: HTMLElement);
-    pin(lines: string[], pos: {
+    pin(grid: TooltipContent, pos: {
         px: number;
         py: number;
-    }, bounds: CssBounds): void;
+    }, bounds: CssBounds, style?: TooltipStyle): void;
     dismiss(): void;
     setCursor(cursor: string): void;
 }

package/dist/esm/interaction/host-sink-message.d.ts

@@ -1,5 +1,6 @@
 import type { DismissTooltipMsg, PinTooltipMsg, SetCursorMsg, UserClickMsg, UserSelectMsg } from "../transport/protocol";
 import type { CssBounds, HostSink, UserClickPayload, UserSelectPayload } from "./tooltip-controller";
+import { type TooltipContent, type TooltipStyle } from "./tooltip-grid";
 /**
  * The subset of `WorkerMsg`s that flow chart → host through a
  * `MessageHostSink`. Identical to the worker-side post payloads so the
@@ -17,10 +18,10 @@ export type HostSinkEnvelope = PinTooltipMsg | DismissTooltipMsg | SetCursorMsg
 export declare class MessageHostSink implements HostSink {
     private _send;
     constructor(send: (msg: HostSinkEnvelope) => void);
-    pin(lines: string[], pos: {
+    pin(grid: TooltipContent, pos: {
         px: number;
         py: number;
-    }, bounds: CssBounds): void;
+    }, bounds: CssBounds, style?: TooltipStyle): void;
     dismiss(): void;
     setCursor(cursor: string): void;
     emitUserClick(payload: UserClickPayload): void;

package/dist/esm/interaction/lazy-tooltip.d.ts

@@ -20,7 +20,7 @@ export declare class LazyTooltip<Target> {
     /**
      * Cached lines for the latest committed hover, or `null`.
      */
-    lines: string[] | null;
+    grid: string[][] | null;
     /**
      * Identity of the entity `lines` describe. `null` when cleared.
      */
@@ -40,7 +40,7 @@ export declare class LazyTooltip<Target> {
      * when the write happened (caller should repaint), false when the
      * serial was stale.
      */
-    commitHover(serial: number, lines: string[]): boolean;
+    commitHover(serial: number, grid: string[][]): boolean;
     /**
      * Clear hover state (mouse left, view changed, etc.).
      */