@perspective-dev/viewer-charts 4.5.2 → 5.1.0

package/src/ts/charts/series/glyphs/draw-scatter.ts

@@ -34,10 +34,22 @@ interface ScatterProgramCache {
  * Persistent scatter glyph state — left/right axis position + color
  * buffers built once at data load. Pan/zoom redraws rebind without
  * uploading.
+ *
+ * `seriesRanges` records each visible series' contiguous run within
+ * its axis bucket (`first` is bucket-relative). The fill loop appends
+ * series in order, so runs are contiguous by construction; the
+ * faceted draw path uses them to dispatch per-facet sub-ranges via
+ * `drawArrays(POINTS, first, count)`.
  */
 interface ScatterBuffers {
     leftCount: number;
     rightCount: number;
+    seriesRanges: {
+        seriesId: number;
+        axis: 0 | 1;
+        first: number;
+        count: number;
+    }[];
 }
 
 /**
@@ -170,6 +182,9 @@ export class ScatterGlyph {
 
         // Fill left bucket from `[0, leftCount)`, right bucket from
         // `[leftCount, total)` — single typed-array allocation each.
+        // Series runs are contiguous within their bucket; record each
+        // run's bucket-relative `[first, count)` for the faceted draw.
+        const seriesRanges: ScatterBuffers["seriesRanges"] = [];
         let leftWrite = 0;
         let rightWrite = leftCount;
         for (const s of scatterSeries) {
@@ -177,6 +192,7 @@ export class ScatterGlyph {
                 continue;
             }
 
+            const runFirst = s.axis === 1 ? rightWrite - leftCount : leftWrite;
             const r = s.color[0];
             const g = s.color[1];
             const b = s.color[2];
@@ -204,6 +220,16 @@ export class ScatterGlyph {
                     leftWrite++;
                 }
             }
+
+            const runEnd = s.axis === 1 ? rightWrite - leftCount : leftWrite;
+            if (runEnd > runFirst) {
+                seriesRanges.push({
+                    seriesId: s.seriesId,
+                    axis: s.axis,
+                    first: runFirst,
+                    count: runEnd - runFirst,
+                });
+            }
         }
 
         if (leftCount > 0) {
@@ -236,12 +262,15 @@ export class ScatterGlyph {
             );
         }
 
-        this._buffers = { leftCount, rightCount };
+        this._buffers = { leftCount, rightCount, seriesRanges };
     }
 
     /**
      * Bind the persistent left/right buffers and issue up to two draw
-     * calls. No per-frame allocations or buffer uploads.
+     * calls. No per-frame allocations or buffer uploads. `splitFilter`
+     * (faceted frames) and/or `aggRange` (mixed glyph-run frames)
+     * instead draw each matching series' contiguous bucket sub-range —
+     * one `drawArrays(POINTS, first, count)` per matching series.
      */
     draw(
         chart: SeriesChart,
@@ -249,6 +278,8 @@ export class ScatterGlyph {
         glManager: WebGLContextManager,
         projLeft: Float32Array,
         projRight: Float32Array,
+        splitFilter?: number,
+        aggRange?: { start: number; end: number },
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -267,6 +298,39 @@ export class ScatterGlyph {
             chart._pluginConfig.point_size_px * dpr,
         );
 
+        if (splitFilter !== undefined || aggRange !== undefined) {
+            for (const r of buf.seriesRanges) {
+                if (
+                    splitFilter !== undefined &&
+                    chart._series[r.seriesId].splitIdx !== splitFilter
+                ) {
+                    continue;
+                }
+
+                const aggIdx = chart._series[r.seriesId].aggIdx;
+                if (
+                    aggRange !== undefined &&
+                    (aggIdx < aggRange.start || aggIdx > aggRange.end)
+                ) {
+                    continue;
+                }
+
+                drawBucket(
+                    gl,
+                    cache,
+                    r.axis === 1 ? cache.posRightBuffer : cache.posLeftBuffer,
+                    r.axis === 1
+                        ? cache.colorRightBuffer
+                        : cache.colorLeftBuffer,
+                    r.count,
+                    r.axis === 1 ? projRight : projLeft,
+                    r.first,
+                );
+            }
+
+            return;
+        }
+
         drawBucket(
             gl,
             cache,
@@ -309,6 +373,7 @@ function drawBucket(
     colBuf: WebGLBuffer,
     count: number,
     proj: Float32Array,
+    first = 0,
 ): void {
     if (count === 0) {
         return;
@@ -324,5 +389,5 @@ function drawBucket(
     gl.enableVertexAttribArray(cache.a_color);
     gl.vertexAttribPointer(cache.a_color, 3, gl.FLOAT, false, 0, 0);
 
-    gl.drawArrays(gl.POINTS, 0, count);
+    gl.drawArrays(gl.POINTS, first, count);
 }

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

@@ -285,6 +285,18 @@ export interface SeriesPipelineInput {
      */
     includeZero: boolean;
 
+    /**
+     * `facet_mode: "grid"` geometry: key the stack ladder by
+     * `(catIdx, aggIdx, splitIdx)` instead of `(catIdx, aggIdx)`, so
+     * splits never stack on each other — each facet's bars / areas
+     * grow from their own zero baseline. Slot geometry (`xCenter` /
+     * `halfWidth`) is unchanged: facets separate splits by projection
+     * + scissor, not by X offset, so every split's records share the
+     * same band-slot coordinates. Value extents still accumulate
+     * across ALL splits — the facet grid renders a shared value axis.
+     */
+    facetSplits?: boolean;
+
     /**
      * Reusable scratch — pipeline writes records into these in place
      * and zero-fills the stack ladder. Pass the previous build's
@@ -404,6 +416,7 @@ export function buildSeriesPipeline(
         bandInnerFrac,
         barInnerPad,
         includeZero,
+        facetSplits,
         scratchBars,
         scratchPosStack,
         scratchNegStack,
@@ -529,9 +542,12 @@ export function buildSeriesPipeline(
     const N = numCategories;
     const S = series.length;
 
-    // Stacking ladder, keyed by (catIdx, aggIdx). Reuse chart-owned
+    // Stacking ladder, keyed by (catIdx, aggIdx) — or per-split
+    // (catIdx, aggIdx, splitIdx) in facet-grid mode, where each split
+    // renders in its own facet and cross-split stacking would lift
+    // every facet after the first off its baseline. Reuse chart-owned
     // scratch when sized; else allocate. Active prefix is zero-filled.
-    const stackLen = N * M;
+    const stackLen = facetSplits ? N * M * P : N * M;
     const posStack = ensureFloat64Scratch(scratchPosStack ?? null, stackLen);
     const negStack = ensureFloat64Scratch(scratchNegStack ?? null, stackLen);
     posStack.fill(0, 0, stackLen);
@@ -922,7 +938,9 @@ export function buildSeriesPipeline(
                         }
                     }
 
-                    const stackIdx = catI * M + k;
+                    const stackIdx = facetSplits
+                        ? (catI * M + k) * P + p
+                        : catI * M + k;
                     let y0: number;
                     let y1: number;
                     if (v >= 0) {

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

@@ -18,10 +18,10 @@ import {
     type SeriesChartRecord,
 } from "./series-build";
 import {
-    renderBarFrame,
     uploadBarInstances,
     rebuildGlyphBuffers,
     rightAxisDataToPixel,
+    layoutForRecord,
 } from "./series-render";
 
 const POINT_HIT_RADIUS_PX = 10;
@@ -47,9 +47,16 @@ export function getHoveredBar(chart: SeriesChart): SeriesChartRecord | null {
 }
 
 /**
- * Handle mouse-move across all glyph types. Tests (in reverse paint order
- * so top glyphs win): scatter points → line points → bars → areas.
+ * Handle mouse-move across all glyph types. Tests glyph runs in reverse
+ * paint order so top glyphs win — paint order is the `columns`
+ * declaration order (see `_glyphRuns` / `drawGlyphRuns`).
  * Updates `_hoveredBarIdx` or `_hoveredSample` and re-renders on change.
+ *
+ * Faceted frames first resolve the cell under the cursor: that cell's
+ * layout supplies the pixel→data mapping and its index becomes the
+ * `splitFilter` — records of other splits share the same band-slot
+ * coordinates by construction, so an unfiltered hit-test would match
+ * a bar from a different facet.
  */
 export function handleBarHover(
     chart: SeriesChart,
@@ -60,7 +67,33 @@ export function handleBarHover(
         return;
     }
 
-    const layout = chart._lastLayout;
+    let layout = chart._lastLayout;
+    let splitFilter: number | undefined;
+    if (chart._facetGrid) {
+        const cells = chart._facetGrid.cells;
+        let found = -1;
+        for (let i = 0; i < cells.length; i++) {
+            const p = cells[i].layout.plotRect;
+            if (
+                mx >= p.x &&
+                mx <= p.x + p.width &&
+                my >= p.y &&
+                my <= p.y + p.height
+            ) {
+                found = i;
+                break;
+            }
+        }
+
+        if (found < 0) {
+            clearHover(chart);
+            return;
+        }
+
+        layout = cells[found].layout;
+        splitFilter = found;
+    }
+
     const plot = layout.plotRect;
 
     if (
@@ -121,83 +154,131 @@ export function handleBarHover(
     let nextBarIdx = -1;
     let nextSample: SeriesChartRecord | null = null;
 
-    // 1. Scatter (top).
-    nextSample = hitTestPoints(
-        chart,
-        "scatter",
-        dataX,
-        dataYLeft,
-        dataYRight,
-        pxPerDataX,
-        pxPerDataYLeft,
-        pxPerDataYRight,
-    );
+    // Test topmost-first: the REVERSE of the paint order, which is the
+    // `columns` declaration order (`_glyphRuns`, ascending `aggIdx` —
+    // see `drawGlyphRuns`). A single-run chart passes no `aggRange`,
+    // reducing to the legacy whole-type scan.
+    const runs = chart._glyphRuns;
+    const single = runs.length <= 1;
+    for (let r = runs.length - 1; r >= 0; r--) {
+        const run = runs[r];
+        const aggRange = single
+            ? undefined
+            : { start: run.aggStart, end: run.aggEnd };
+        switch (run.chartType) {
+            case "scatter":
+            case "line":
+                nextSample = hitTestPoints(
+                    chart,
+                    run.chartType,
+                    dataX,
+                    dataYLeft,
+                    dataYRight,
+                    pxPerDataX,
+                    pxPerDataYLeft,
+                    pxPerDataYRight,
+                    splitFilter,
+                    aggRange,
+                );
+                break;
+            case "bar":
+                nextBarIdx = hitTestBars(
+                    chart,
+                    dataX,
+                    dataYLeft,
+                    dataYRight,
+                    splitFilter,
+                    aggRange,
+                );
+                break;
+            case "area": {
+                const areaHit = hitTestAreas(
+                    chart,
+                    dataX,
+                    dataYLeft,
+                    dataYRight,
+                    splitFilter,
+                    aggRange,
+                );
+                if (areaHit) {
+                    if (areaHit.idx >= 0) {
+                        nextBarIdx = areaHit.idx;
+                    } else {
+                        nextSample = areaHit.bar;
+                    }
+                }
 
-    // 2. Line points (still above bars; treat as point hits).
-    if (!nextSample) {
-        nextSample = hitTestPoints(
-            chart,
-            "line",
-            dataX,
-            dataYLeft,
-            dataYRight,
-            pxPerDataX,
-            pxPerDataYLeft,
-            pxPerDataYRight,
-        );
+                break;
+            }
+        }
+
+        if (nextBarIdx >= 0 || nextSample) {
+            break;
+        }
     }
 
-    // 3. Bars (rect intersect).
-    if (!nextSample) {
-        const bars = chart._bars;
-        const ct = bars.chartType;
-        const sid = bars.seriesId;
-        const xC = bars.xCenter;
-        const hw = bars.halfWidth;
-        const by0 = bars.y0;
-        const by1 = bars.y1;
-        const ax = bars.axis;
-        const hidden = chart._hiddenSeries;
-        for (let i = 0; i < bars.count; i++) {
-            if (ct[i] !== BAR_TYPE_BAR) {
-                continue;
-            }
+    applyHover(chart, nextBarIdx, nextSample);
+}
 
-            if (hidden.has(sid[i])) {
-                continue;
-            }
+/**
+ * Rect-intersect hit-test over the bar-typed `_bars` records. Returns
+ * the record index, or `-1`.
+ */
+function hitTestBars(
+    chart: SeriesChart,
+    dataX: number,
+    dataYLeft: number,
+    dataYRight: number,
+    splitFilter?: number,
+    aggRange?: { start: number; end: number },
+): number {
+    const bars = chart._bars;
+    const ct = bars.chartType;
+    const sid = bars.seriesId;
+    const xC = bars.xCenter;
+    const hw = bars.halfWidth;
+    const by0 = bars.y0;
+    const by1 = bars.y1;
+    const ax = bars.axis;
+    const hidden = chart._hiddenSeries;
+    const P = Math.max(1, chart._splitPrefixes.length);
+    for (let i = 0; i < bars.count; i++) {
+        if (ct[i] !== BAR_TYPE_BAR) {
+            continue;
+        }
 
-            const xc = xC[i];
-            const halfW = hw[i];
-            if (dataX < xc - halfW || dataX > xc + halfW) {
+        if (hidden.has(sid[i])) {
+            continue;
+        }
+
+        if (splitFilter !== undefined && sid[i] % P !== splitFilter) {
+            continue;
+        }
+
+        if (aggRange !== undefined) {
+            const aggIdx = Math.floor(sid[i] / P);
+            if (aggIdx < aggRange.start || aggIdx > aggRange.end) {
                 continue;
             }
+        }
 
-            const dy = ax[i] === 0 ? dataYLeft : dataYRight;
-            const y0 = by0[i];
-            const y1 = by1[i];
-            const lo = y0 < y1 ? y0 : y1;
-            const hi = y0 < y1 ? y1 : y0;
-            if (dy >= lo && dy <= hi) {
-                nextBarIdx = i;
-                break;
-            }
+        const xc = xC[i];
+        const halfW = hw[i];
+        if (dataX < xc - halfW || dataX > xc + halfW) {
+            continue;
         }
-    }
 
-    // 4. Areas (strip hit — stacked records via `_bars`, unstacked via samples).
-    if (nextBarIdx < 0 && !nextSample) {
-        const areaHit = hitTestAreas(chart, dataX, dataYLeft, dataYRight);
-        if (areaHit) {
-            if (areaHit.idx >= 0) {
-                nextBarIdx = areaHit.idx;
-            } else {
-                nextSample = areaHit.bar;
-            }
+        const dy = ax[i] === 0 ? dataYLeft : dataYRight;
+        const y0 = by0[i];
+        const y1 = by1[i];
+        const lo = y0 < y1 ? y0 : y1;
+        const hi = y0 < y1 ? y1 : y0;
+        if (dy >= lo && dy <= hi) {
+            return i;
         }
     }
 
-    applyHover(chart, nextBarIdx, nextSample);
+    return -1;
 }
 
 function hitTestPoints(
@@ -209,6 +290,8 @@ function hitTestPoints(
     pxPerDataX: number,
     pxPerDataYLeft: number,
     pxPerDataYRight: number,
+    splitFilter?: number,
+    aggRange?: { start: number; end: number },
 ): SeriesChartRecord | null {
     const N = chart._numCategories;
     const S = chart._series.length;
@@ -233,6 +316,17 @@ function hitTestPoints(
             continue;
         }
 
+        if (splitFilter !== undefined && s.splitIdx !== splitFilter) {
+            continue;
+        }
+
+        if (
+            aggRange !== undefined &&
+            (s.aggIdx < aggRange.start || s.aggIdx > aggRange.end)
+        ) {
+            continue;
+        }
+
         const dataY = s.axis === 1 ? dataYRight : dataYLeft;
         const pyPerData = s.axis === 1 ? pxPerDataYRight : pxPerDataYLeft;
 
@@ -289,6 +383,8 @@ function hitTestAreas(
     dataX: number,
     dataYLeft: number,
     dataYRight: number,
+    splitFilter?: number,
+    aggRange?: { start: number; end: number },
 ): { idx: number; bar: SeriesChartRecord | null } | null {
     // Closest category to the mouse; an area covers every [cat - 0.5, cat + 0.5]
     // slot, so use `round(dataX)` as the candidate index.
@@ -313,6 +409,7 @@ function hitTestAreas(
     const ax = bars.axis;
     const by0 = bars.y0;
     const by1 = bars.y1;
+    const P = chart._splitPrefixes.length;
     for (let i = 0; i < bars.count; i++) {
         if (ct[i] !== BAR_TYPE_AREA) {
             continue;
@@ -326,6 +423,17 @@ function hitTestAreas(
             continue;
         }
 
+        if (splitFilter !== undefined && sid[i] % P !== splitFilter) {
+            continue;
+        }
+
+        if (aggRange !== undefined) {
+            const aggIdx = Math.floor(sid[i] / Math.max(1, P));
+            if (aggIdx < aggRange.start || aggIdx > aggRange.end) {
+                continue;
+            }
+        }
+
         const dy = ax[i] === 0 ? dataYLeft : dataYRight;
         const y0 = by0[i];
         const y1 = by1[i];
@@ -346,6 +454,17 @@ function hitTestAreas(
             continue;
         }
 
+        if (splitFilter !== undefined && s.splitIdx !== splitFilter) {
+            continue;
+        }
+
+        if (
+            aggRange !== undefined &&
+            (s.aggIdx < aggRange.start || s.aggIdx > aggRange.end)
+        ) {
+            continue;
+        }
+
         const idx = cat * S + s.seriesId;
         if (!((valid[idx >> 3] >> (idx & 7)) & 1)) {
             continue;
@@ -383,7 +502,7 @@ function clearHover(chart: SeriesChart): void {
         chart._hoveredBarIdx = -1;
         chart._hoveredSample = null;
         if (chart._glManager) {
-            renderBarFrame(chart, chart._glManager);
+            chart.requestRender(chart._glManager);
         }
     }
 }
@@ -405,13 +524,17 @@ function applyHover(
     chart._hoveredBarIdx = nextBarIdx;
     chart._hoveredSample = nextSample;
     if (chart._glManager) {
-        renderBarFrame(chart, chart._glManager);
+        chart.requestRender(chart._glManager);
     }
 }
 
 /**
  * Handle a click on the legend area. Returns true when the click hit a
  * legend entry (the caller should then treat the event as consumed).
+ *
+ * An entry may own several series (facet-grid mode groups the legend
+ * by aggregate): the toggle is all-or-nothing — any visible member
+ * hides the whole group, a fully-hidden group shows every member.
  */
 export function handleBarLegendClick(
     chart: SeriesChart,
@@ -430,10 +553,15 @@ export function handleBarLegendClick(
             my >= r.y &&
             my <= r.y + r.height
         ) {
-            if (chart._hiddenSeries.has(entry.seriesId)) {
-                chart._hiddenSeries.delete(entry.seriesId);
-            } else {
-                chart._hiddenSeries.add(entry.seriesId);
+            const anyVisible = entry.seriesIds.some(
+                (sid) => !chart._hiddenSeries.has(sid),
+            );
+            for (const sid of entry.seriesIds) {
+                if (anyVisible) {
+                    chart._hiddenSeries.add(sid);
+                } else {
+                    chart._hiddenSeries.delete(sid);
+                }
             }
 
             // Hidden-series change affects which bars contribute to
@@ -454,7 +582,7 @@ export function handleBarLegendClick(
             if (chart._glManager) {
                 uploadBarInstances(chart, chart._glManager);
                 rebuildGlyphBuffers(chart, chart._glManager);
-                renderBarFrame(chart, chart._glManager);
+                chart.requestRender(chart._glManager);
             }
 
             return true;
@@ -571,7 +699,11 @@ function pinTooltip(chart: SeriesChart, b: SeriesChartRecord): void {
         return;
     }
 
-    const layout = chart._lastLayout;
+    // Faceted frames anchor in the record's own cell.
+    const layout = layoutForRecord(chart, b);
+    if (!layout) {
+        return;
+    }
 
     // Anchor at the bar midpoint for bar glyphs (tooltip reads against
     // the body); at the point itself (`y1`) for line / scatter / area.
@@ -582,7 +714,7 @@ function pinTooltip(chart: SeriesChart, b: SeriesChartRecord): void {
             ? chart._isHorizontal
                 ? layout.dataToPixel(anchorV, b.xCenter)
                 : layout.dataToPixel(b.xCenter, anchorV)
-            : rightAxisDataToPixel(chart, b.xCenter, anchorV);
+            : rightAxisDataToPixel(chart, b.xCenter, anchorV, layout);
 
     const lines = buildBarTooltipLines(chart, b);
     if (lines.length === 0) {
@@ -594,7 +726,7 @@ function pinTooltip(chart: SeriesChart, b: SeriesChartRecord): void {
     chart._hoveredBarIdx = -1;
     chart._hoveredSample = null;
     if (chart._glManager) {
-        renderBarFrame(chart, chart._glManager);
+        chart.requestRender(chart._glManager);
     }
 }