@perspective-dev/viewer-charts 5.3.0 → 5.4.0

package/src/ts/charts/common/tree-chrome.ts

@@ -17,12 +17,21 @@ import type { GradientStop } from "../../theme/gradient";
 import type { Vec3 } from "../../theme/palette";
 import type { Theme } from "../../theme/theme";
 import {
+    gradientLegendAutoFit,
+    legendAutoFit,
     renderCategoricalLegend,
     renderCategoricalLegendAt,
     renderLegend,
+    renderLegendAt,
+    type LegendPaintView,
 } from "../../axis/legend";
+import {
+    legendSidebarWidth,
+    resolveLegendMode,
+} from "../../interaction/legend-controller";
 import type { TreeChartBase } from "./tree-chart";
 import { drawTooltipBox } from "./draw-tooltip-box";
+import { tooltipStyleOf } from "../../interaction/tooltip-grid";
 
 /**
  * Click target for one breadcrumb segment. Tree-chart hit-testing
@@ -112,23 +121,24 @@ export function renderTreeTooltip(
     cssHeight: number,
     fontFamily: string,
 ): void {
-    const lines =
+    const grid =
         chart._lazyTooltip.hoveredTarget === nodeId
-            ? (chart._lazyTooltip.lines ?? [])
+            ? (chart._lazyTooltip.grid ?? [])
             : [];
-    if (lines.length === 0) {
+    if (grid.length === 0) {
         return;
     }
 
     drawTooltipBox(
         ctx,
         chart._resolveTheme(),
-        lines,
+        grid,
         cx,
         cy,
         cssWidth,
         cssHeight,
         fontFamily,
+        tooltipStyleOf(chart._pluginConfig),
     );
 }
 
@@ -159,50 +169,119 @@ export function renderTreeColorLegend(
     cssHeight: number,
     categoricalRect: PlotRect | null = null,
 ): void {
-    if (chart._colorMode === "series" && chart._uniqueColorLabels.size > 1) {
-        if (categoricalRect) {
+    const cfg = chart._pluginConfig;
+    const hasCategorical =
+        chart._colorMode === "series" && chart._uniqueColorLabels.size > 1;
+    const hasNumeric =
+        chart._colorMode === "numeric" && chart._colorMin < chart._colorMax;
+    const mode = resolveLegendMode(
+        cfg,
+        hasCategorical ? chart._uniqueColorLabels.size : 0,
+    );
+    if (mode === "none" || (!hasCategorical && !hasNumeric)) {
+        chart._legend.clearPainted();
+        return;
+    }
+
+    const floating = mode === "floating";
+    const view: LegendPaintView = {
+        mode: floating ? "floating" : "sidebar",
+        legend: chart._legend,
+        title: chart._colorName || "Legend",
+        opacity: cfg.legend_opacity,
+    };
+    const floatBox = floating
+        ? chart._legend.floatingBox(
+              cfg,
+              cssWidth,
+              cssHeight,
+              hasCategorical
+                  ? legendAutoFit(
+                        canvas,
+                        theme,
+                        chart._uniqueColorLabels.size,
+                        () => chart._uniqueColorLabels.keys(),
+                        { title: view.title },
+                    )
+                  : gradientLegendAutoFit(
+                        canvas,
+                        theme,
+                        { min: chart._colorMin, max: chart._colorMax },
+                        undefined,
+                        view.title,
+                    ),
+          )
+        : null;
+
+    if (hasCategorical) {
+        if (floatBox) {
+            renderCategoricalLegendAt(
+                canvas,
+                floatBox,
+                chart._uniqueColorLabels,
+                palette,
+                theme,
+                view,
+            );
+        } else if (categoricalRect) {
             renderCategoricalLegendAt(
                 canvas,
                 categoricalRect,
                 chart._uniqueColorLabels,
                 palette,
                 theme,
+                { ...view, sidebarGutter: categoricalRect.width },
             );
         } else {
             renderCategoricalLegend(
                 canvas,
-                syntheticLegendLayout(cssWidth, cssHeight),
+                syntheticLegendLayout(cssWidth, cssHeight, cfg),
                 chart._uniqueColorLabels,
                 palette,
                 theme,
+                view,
+            );
+        }
+    } else {
+        const colorDomain = {
+            min: chart._colorMin,
+            max: chart._colorMax,
+            label: chart._colorName,
+        };
+        const formatter = chart.getColumnFormatter(chart._colorName, "value");
+        if (floatBox) {
+            renderLegendAt(
+                canvas,
+                floatBox,
+                colorDomain,
+                stops,
+                theme,
+                formatter,
+                view,
+            );
+        } else {
+            renderLegend(
+                canvas,
+                syntheticLegendLayout(cssWidth, cssHeight, cfg),
+                colorDomain,
+                stops,
+                theme,
+                formatter,
+                view,
             );
         }
-    } else if (
-        chart._colorMode === "numeric" &&
-        chart._colorMin < chart._colorMax
-    ) {
-        renderLegend(
-            canvas,
-            syntheticLegendLayout(cssWidth, cssHeight),
-            {
-                min: chart._colorMin,
-                max: chart._colorMax,
-                label: chart._colorName,
-            },
-            stops,
-            theme,
-            chart.getColumnFormatter(chart._colorName, "value"),
-        );
     }
 }
 
 function syntheticLegendLayout(
     cssWidth: number,
     cssHeight: number,
+    cfg: TreeChartBase["_pluginConfig"],
 ): PlotLayout {
     return new PlotLayout(cssWidth, cssHeight, {
         hasXLabel: false,
         hasYLabel: false,
         hasLegend: true,
+        rightExtra: legendSidebarWidth(cfg, 80),
     });
 }

package/src/ts/charts/common/tree-interact.ts

@@ -13,6 +13,7 @@
 import type { TreeChartBase } from "./tree-chart";
 import { NULL_NODE, ancestorNames } from "./node-store";
 import { rebuildBreadcrumbs } from "./tree-data";
+import { tooltipStyleOf } from "../../interaction/tooltip-grid";
 
 /**
  * Common subset of `TreemapChart` / `SunburstChart` reached by the
@@ -73,9 +74,9 @@ export async function emitTreeNodeEvent(
 export async function buildTreeTooltipLines(
     chart: TreeInteractChart,
     nodeId: number,
-): Promise<string[]> {
+): Promise<string[][]> {
     const store = chart._nodeStore;
-    const lines: string[] = [];
+    const grid: string[][] = [];
 
     const pathNames: string[] = [];
     let p = nodeId;
@@ -86,19 +87,17 @@ export async function buildTreeTooltipLines(
 
     pathNames.reverse();
     if (pathNames.length > 0) {
-        lines.push(pathNames.join(" › "));
+        grid.push([pathNames.join(" › ")]);
     } else {
-        lines.push(store.name[nodeId]);
+        grid.push([store.name[nodeId]]);
     }
 
     const sizeFmt = chart.getColumnFormatter(chart._sizeName, "value");
-    lines.push(`Value: ${sizeFmt(store.value[nodeId])}`);
+    grid.push(["Value", sizeFmt(store.value[nodeId])]);
 
     if (chart._colorName && !isNaN(store.colorValue[nodeId])) {
         const colorFmt = chart.getColumnFormatter(chart._colorName, "value");
-        lines.push(
-            `${chart._colorName}: ${colorFmt(store.colorValue[nodeId])}`,
-        );
+        grid.push([chart._colorName, colorFmt(store.colorValue[nodeId])]);
     }
 
     const rowIdx = store.leafRowIdx[nodeId];
@@ -117,20 +116,21 @@ export async function buildTreeTooltipLines(
             }
 
             if (typeof value === "number") {
-                lines.push(
-                    `${name}: ${chart.getColumnFormatter(name, "value")(value)}`,
-                );
+                grid.push([
+                    name,
+                    chart.getColumnFormatter(name, "value")(value),
+                ]);
             } else {
-                lines.push(`${name}: ${value}`);
+                grid.push([name, String(value)]);
             }
         }
     }
 
     if (store.firstChild[nodeId] !== NULL_NODE) {
-        lines.push(`Children: ${store.childCount[nodeId]}`);
+        grid.push(["Children", String(store.childCount[nodeId])]);
     }
 
-    return lines;
+    return grid;
 }
 
 /**
@@ -150,19 +150,20 @@ export function showTreePinnedTooltip(
     const cssWidth = chart._glManager?.cssWidth ?? 0;
     const cssHeight = chart._glManager?.cssHeight ?? 0;
 
-    buildTreeTooltipLines(chart, nodeId).then((lines) => {
+    buildTreeTooltipLines(chart, nodeId).then((grid) => {
         if (chart._pinnedNodeId !== nodeId) {
             return;
         }
 
-        if (lines.length === 0) {
+        if (grid.length === 0) {
             return;
         }
 
         chart._tooltip.pin(
-            lines,
+            grid,
             { px: anchor.cx, py: anchor.cy },
             { cssWidth, cssHeight },
+            tooltipStyleOf(chart._pluginConfig),
         );
     });
 

package/src/ts/charts/heatmap/heatmap-interact.ts

@@ -13,6 +13,12 @@
 import type { HeatmapChart } from "./heatmap";
 import type { HeatmapCell } from "./heatmap-build";
 import { renderCanvasTooltip } from "../../interaction/tooltip-controller";
+import {
+    renderAxisHoverIndicators,
+    type AxisIndicator,
+} from "../../interaction/axis-indicators";
+import { computeNiceTicks, stepTickFormatter } from "../../layout/ticks";
+import { tooltipStyleOf } from "../../interaction/tooltip-grid";
 import type { CategoricalLevel } from "../../axis/categorical-axis";
 
 /**
@@ -216,6 +222,8 @@ export function renderHeatmapTooltip(chart: HeatmapChart): void {
     let xLevels: CategoricalLevel[];
     let yLevels: CategoricalLevel[];
     let xPositions: Float64Array | null;
+    let yPositions: Float64Array | null;
+    let xNumericDomain: { isDate?: boolean } | null;
     let facetLabel: string | null = null;
 
     if (chart._hoveredFacetIdx >= 0) {
@@ -228,6 +236,8 @@ export function renderHeatmapTooltip(chart: HeatmapChart): void {
         xLevels = facet.pipeline.xLevels;
         yLevels = facet.pipeline.yLevels;
         xPositions = facet.pipeline.xPositions;
+        yPositions = facet.pipeline.yPositions;
+        xNumericDomain = facet.pipeline.xNumericDomain;
         facetLabel = facet.label;
     } else {
         if (!chart._lastLayout) {
@@ -238,6 +248,8 @@ export function renderHeatmapTooltip(chart: HeatmapChart): void {
         xLevels = chart._xLevels;
         yLevels = chart._yLevels;
         xPositions = chart._xPositions;
+        yPositions = chart._yPositions;
+        xNumericDomain = chart._xNumericDomain;
     }
 
     const cell = chart._hoveredCell;
@@ -247,9 +259,9 @@ export function renderHeatmapTooltip(chart: HeatmapChart): void {
     // many pixels.
     const pos = { px: chart._hoveredMouseX, py: chart._hoveredMouseY };
 
-    const lines: string[] = [];
+    const grid: string[][] = [];
     if (facetLabel) {
-        lines.push(facetLabel);
+        grid.push([facetLabel]);
     }
 
     const xPath =
@@ -261,23 +273,69 @@ export function renderHeatmapTooltip(chart: HeatmapChart): void {
             : formatHierarchicalPath(xLevels, cell.xIdx);
     const yPath = formatHierarchicalPath(yLevels, cell.yIdx);
     if (xPath) {
-        lines.push(xPath);
+        grid.push([xPath]);
     }
 
     if (yPath) {
-        lines.push(yPath);
+        grid.push([yPath]);
     }
 
     const valueFmt = chart.getColumnFormatter(chart._columnSlots[0], "value");
-    lines.push(`Value: ${valueFmt(cell.value)}`);
+    grid.push(["Value", valueFmt(cell.value)]);
 
     const theme = chart._resolveTheme();
+    const dpr = chart._glManager?.dpr ?? 1;
+
+    const cellPos = layout.dataToPixel(
+        xPositions ? xPositions[cell.xIdx] : cell.xIdx,
+        yPositions ? yPositions[cell.yIdx] : cell.yIdx,
+    );
+    const badgeX =
+        chart._xAxisMode.mode === "numeric" && xPositions
+            ? (
+                  chart.getColumnFormatter(chart._groupBy[0], "tick") ??
+                  stepTickFormatter(
+                      xNumericDomain?.isDate,
+                      computeNiceTicks(layout.paddedXMin, layout.paddedXMax, 6),
+                  )
+              )(xPositions[cell.xIdx])
+            : xPath;
+
+    const indicators: AxisIndicator[] = [];
+    if (badgeX) {
+        indicators.push({
+            side: "bottom",
+            px: cellPos.px,
+            py: cellPos.py,
+            text: badgeX,
+        });
+    }
+
+    if (yPath) {
+        indicators.push({
+            side: "left",
+            px: cellPos.px,
+            py: cellPos.py,
+            text: yPath,
+        });
+    }
+
+    renderAxisHoverIndicators(
+        chart._chromeCanvas,
+        layout,
+        theme,
+        dpr,
+        indicators,
+        chart._pluginConfig.tooltip_opacity,
+    );
+
     renderCanvasTooltip(
         chart._chromeCanvas,
         pos,
-        lines,
+        grid,
         layout,
         theme,
-        chart._glManager?.dpr ?? 1,
+        dpr,
+        tooltipStyleOf(chart._pluginConfig),
     );
 }

package/src/ts/charts/heatmap/heatmap-render.ts

@@ -47,7 +47,17 @@ const HEATMAP_Y_AXIS_OPTS: CategoricalYAxisOptions = {
     skipLeafLevel: true,
 };
 
-import { renderLegend, renderLegendAt } from "../../axis/legend";
+import {
+    gradientLegendAutoFit,
+    renderLegend,
+    renderLegendAt,
+    type LegendPaintView,
+} from "../../axis/legend";
+import {
+    legendRightGutter,
+    resolveLegendMode,
+    legendSidebarWidth,
+} from "../../interaction/legend-controller";
 import heatmapVert from "../../shaders/heatmap.vert.glsl";
 import heatmapFrag from "../../shaders/heatmap.frag.glsl";
 import { colorValueToT } from "../../theme/gradient";
@@ -110,6 +120,7 @@ export function renderHeatmapFrame(
     // Measure both hierarchical axes *before* building the layout so the
     // plot rect accounts for their footprints. Numeric axes get fixed
     // gutters matching bar's branch (24px bottom, 55px left).
+    const rightExtra = legendRightGutter(chart._pluginConfig, true, 80, 0);
     const estLeft = yNumeric
         ? 55
         : measureCategoricalAxisWidth(yDomain, HEATMAP_Y_AXIS_OPTS);
@@ -117,7 +128,7 @@ export function renderHeatmapFrame(
         ? 24
         : measureCategoricalAxisHeight(
               xDomain,
-              Math.max(1, cssWidth - estLeft - 110),
+              Math.max(1, cssWidth - estLeft - 30 - rightExtra),
           );
 
     const layout = new PlotLayout(cssWidth, cssHeight, {
@@ -126,6 +137,7 @@ export function renderHeatmapFrame(
         hasLegend: true,
         bottomExtra,
         leftExtra: estLeft,
+        rightExtra,
     });
     chart._lastLayout = layout;
     if (chart._zoomController) {
@@ -482,20 +494,58 @@ function paintHeatmapChromeOverlay(chart: HeatmapChart): void {
         );
     }
 
-    // Color legend on the right. The aggregate column name is in
-    // `_columnSlots[0]` (heatmap's only data column slot is "Color").
-    renderLegend(
-        chart._chromeCanvas,
-        layout,
-        {
+    const legendMode = resolveLegendMode(chart._pluginConfig, 0);
+    if (legendMode === "none") {
+        chart._legend.clearPainted();
+    } else {
+        const colorDomain = {
             min: chart._colorMin,
             max: chart._colorMax,
             label: chart._aggName,
-        },
-        theme.gradientStops,
-        theme,
-        chart.getColumnFormatter(chart._columnSlots[0], "value"),
-    );
+        };
+        const formatter = chart.getColumnFormatter(
+            chart._columnSlots[0],
+            "value",
+        );
+        const view: LegendPaintView = {
+            mode: legendMode === "floating" ? "floating" : "sidebar",
+            legend: chart._legend,
+            title: chart._aggName,
+            opacity: chart._pluginConfig.legend_opacity,
+        };
+        if (legendMode === "floating") {
+            renderLegendAt(
+                chart._chromeCanvas,
+                chart._legend.floatingBox(
+                    chart._pluginConfig,
+                    layout.cssWidth,
+                    layout.cssHeight,
+                    gradientLegendAutoFit(
+                        chart._chromeCanvas,
+                        theme,
+                        colorDomain,
+                        formatter,
+                        chart._aggName,
+                    ),
+                ),
+                colorDomain,
+                theme.gradientStops,
+                theme,
+                formatter,
+                view,
+            );
+        } else {
+            renderLegend(
+                chart._chromeCanvas,
+                layout,
+                colorDomain,
+                theme.gradientStops,
+                theme,
+                formatter,
+                view,
+            );
+        }
+    }
 
     if (chart._hoveredCell) {
         renderHeatmapTooltip(chart);
@@ -528,7 +578,8 @@ function renderFacetedHeatmap(
             cssHeight,
             xAxis: effectiveSharedX ? "outer" : "cell",
             yAxis: effectiveSharedY ? "outer" : "cell",
-            hasLegend: true,
+            hasLegend: resolveLegendMode(chart._pluginConfig, 0) === "sidebar",
+            legendWidth: legendSidebarWidth(chart._pluginConfig, 96),
             hasXLabel: chart._groupBy.length > 0,
             hasYLabel: false,
             gap: 8,
@@ -793,18 +844,34 @@ function renderFacetedHeatmapChromeOverlay(chart: HeatmapChart): void {
         );
     }
 
-    // Shared colorbar at `grid.legendRect`. No meaningful single label —
-    // the facet titles already name each column, and a combined label
-    // would be ambiguous when columns differ.
-    if (grid.legendRect) {
+    const legendMode = resolveLegendMode(chart._pluginConfig, 0);
+    const floating = legendMode === "floating";
+    const facetLayout = chart._facets[0].layout;
+    const legendAnchor = floating
+        ? chart._legend.floatingBox(
+              chart._pluginConfig,
+              facetLayout.cssWidth,
+              facetLayout.cssHeight,
+              gradientLegendAutoFit(
+                  chart._chromeCanvas,
+                  theme,
+                  { min: chart._colorMin, max: chart._colorMax },
+                  chart.getColumnFormatter(chart._columnSlots[0], "value"),
+                  chart._aggName,
+              ),
+          )
+        : grid.legendRect;
+    if (legendMode !== "none" && legendAnchor) {
         renderLegendAt(
             chart._chromeCanvas,
-            {
-                x: grid.legendRect.x,
-                y: grid.legendRect.y + 20,
-                width: grid.legendRect.width,
-                height: Math.max(1, grid.legendRect.height - 20),
-            },
+            floating
+                ? legendAnchor
+                : {
+                      x: legendAnchor.x,
+                      y: legendAnchor.y + 20,
+                      width: legendAnchor.width,
+                      height: Math.max(1, legendAnchor.height - 20),
+                  },
             {
                 min: chart._colorMin,
                 max: chart._colorMax,
@@ -813,7 +880,16 @@ function renderFacetedHeatmapChromeOverlay(chart: HeatmapChart): void {
             theme.gradientStops,
             theme,
             chart.getColumnFormatter(chart._columnSlots[0], "value"),
+            {
+                mode: floating ? "floating" : "sidebar",
+                legend: chart._legend,
+                title: chart._aggName,
+                sidebarGutter: floating ? undefined : grid.legendRect?.width,
+                opacity: chart._pluginConfig.legend_opacity,
+            },
         );
+    } else {
+        chart._legend.clearPainted();
     }
 
     if (chart._hoveredCell) {

package/src/ts/charts/map/map.ts

@@ -22,7 +22,7 @@ import type { Canvas2D, Context2D } from "../canvas-types";
 import type { ZoomConfig } from "../../interaction/zoom-controller";
 import type { PluginConfig } from "../chart";
 import { TileLayer } from "../../map/tile-layer";
-import { tileSourceFor, type TileProviderId } from "../../map/tile-source";
+import { TILE_SOURCES } from "../../map/tile-source";
 import { lonLatToMercator } from "../../map/mercator";
 import { getScaledContext } from "../../axis/canvas";
 
@@ -76,7 +76,7 @@ export class MapChart extends CartesianChart {
         if (this._glManager) {
             this._tileLayer.setSource(
                 this._glManager.gl,
-                tileSourceFor(cfg.map_tile_provider as TileProviderId),
+                TILE_SOURCES.sourceFor(cfg.map_tile_provider),
             );
         }
 
@@ -97,9 +97,7 @@ export class MapChart extends CartesianChart {
         if (!this._tileLayer.source) {
             this._tileLayer.setSource(
                 glManager.gl,
-                tileSourceFor(
-                    this._pluginConfig.map_tile_provider as TileProviderId,
-                ),
+                TILE_SOURCES.sourceFor(this._pluginConfig.map_tile_provider),
             );
             this._tileLayer.setAlpha(this._pluginConfig.map_tile_alpha);
         }

package/src/ts/charts/series/series-build.ts

@@ -336,6 +336,14 @@ 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[];
 
     /**
@@ -477,10 +485,14 @@ export function buildSeriesPipeline(
     );
 
     if (numCategories === 0) {
+        // NOT `aggregates` / `splitPrefixes`: `series` is empty here, and
+        // carrying the non-empty lists would break the `series.length ===
+        // M * P` invariant — `series[k * P]` consumers then read
+        // `undefined` (the `loadAndRender failed … reading 'axis'` crash).
+        // Same shape as the `aggregates.length === 0` return above, which
+        // every downstream path already renders as an empty chart.
         return {
             ...empty,
-            aggregates,
-            splitPrefixes,
             rowPaths,
             rowOffset,
         };