@perspective-dev/viewer-charts 4.5.1 → 5.0.0

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

@@ -156,6 +156,33 @@ function insertRow(
     }
 }
 
+/**
+ * Arrow validity-bitmap test. Columns without a bitmap are all-valid.
+ */
+function isValidCell(col: ColumnData, rowIdx: number): boolean {
+    const v = col.valid;
+    return !v || !!((v[rowIdx >> 3] >> (rowIdx & 7)) & 1);
+}
+
+/**
+ * Read a size cell, honoring the validity bitmap: the bytes under an
+ * invalid slot are UNDEFINED (DuckDB's Arrow leaves NaN where the
+ * engine zero-fills), and a NaN here would poison every ancestor sum
+ * in `finalizeTree`. Invalid → 0 (no contribution); no size column at
+ * all → 1 (count semantics).
+ */
+function readSize(col: ColumnData | null | undefined, rowIdx: number): number {
+    if (!col?.values) {
+        return 1;
+    }
+
+    if (!isValidCell(col, rowIdx)) {
+        return 0;
+    }
+
+    return col.values[rowIdx] as number;
+}
+
 function readColor(
     chart: TreeChartBase,
     colorCol: ColumnData | null | undefined,
@@ -163,7 +190,7 @@ function readColor(
 ): { colorValue: number; colorLabel: string } {
     let colorValue = NaN;
     let colorLabel = "";
-    if (!colorCol) {
+    if (!colorCol || !isValidCell(colorCol, rowIdx)) {
         return { colorValue, colorLabel };
     }
 
@@ -261,7 +288,11 @@ export function processTreeChunk(
     chart: TreeChartBase,
     columns: ColumnDataMap,
 ): void {
-    const rpCols: { indices: Int32Array; dictionary: string[] }[] = [];
+    const rpCols: {
+        indices: Int32Array;
+        dictionary: string[];
+        valid?: Uint8Array;
+    }[] = [];
     for (let n = 0; ; n++) {
         const rp = columns.get(`__ROW_PATH_${n}__`);
         if (!rp) {
@@ -269,7 +300,11 @@ export function processTreeChunk(
         }
 
         if (rp.type === "string" && rp.indices && rp.dictionary) {
-            rpCols.push({ indices: rp.indices, dictionary: rp.dictionary });
+            rpCols.push({
+                indices: rp.indices,
+                dictionary: rp.dictionary,
+                valid: rp.valid,
+            });
         } else if (rp.values) {
             // Non-string group_by (integer / float / date / datetime /
             // boolean) — synthesize a string-indexed dictionary so the
@@ -397,9 +432,7 @@ export function processTreeChunk(
                     // Pass the signed value through; `insertRow` stores
                     // `|size|` and `sizeSign` separately so the
                     // render pass can dim negative leaves.
-                    const sizeValue = src.sizeCol?.values
-                        ? (src.sizeCol.values[i] as number)
-                        : 1;
+                    const sizeValue = readSize(src.sizeCol, i);
                     const { colorValue, colorLabel } = readColor(
                         chart,
                         src.colorCol,
@@ -416,9 +449,7 @@ export function processTreeChunk(
                     );
                 }
             } else {
-                const sizeValue = sizeCol?.values
-                    ? (sizeCol.values[i] as number)
-                    : 1;
+                const sizeValue = readSize(sizeCol, i);
                 const { colorValue, colorLabel } = readColor(
                     chart,
                     colorCol,
@@ -449,6 +480,19 @@ export function processTreeChunk(
         let pathLen = 0;
         for (let d = 0; d < rpCols.length; d++) {
             const rp = rpCols[d];
+
+            // In `"rollup"` mode the view emits total / subtotal rows
+            // whose deeper row-path levels are INVALID — index slot 0,
+            // which decodes to a REAL dictionary value (the engine's
+            // string row-path dictionaries carry no `""` sentinel), so
+            // the validity bitmap is the only truthful signal. Truncate
+            // the path at the first invalid level; the `!label` check
+            // below still covers synthesized non-string levels, whose
+            // dictionary index 0 IS the `""` sentinel.
+            if (rp.valid && !((rp.valid[i >> 3] >> (i & 7)) & 1)) {
+                break;
+            }
+
             const label = rp.dictionary[rp.indices[i]];
             if (!label && label !== "0") {
                 break;
@@ -465,9 +509,7 @@ export function processTreeChunk(
             for (const src of splitSources!) {
                 pathScratch[0] = src.prefix;
                 const rowPath = pathScratch.slice(0, pathLen + 1);
-                const sizeValue = src.sizeCol?.values
-                    ? (src.sizeCol.values[i] as number)
-                    : 1;
+                const sizeValue = readSize(src.sizeCol, i);
                 const { colorValue, colorLabel } = readColor(
                     chart,
                     src.colorCol,
@@ -485,9 +527,7 @@ export function processTreeChunk(
             }
         } else {
             const rowPath = pathScratch.slice(0, pathLen);
-            const sizeValue = sizeCol?.values
-                ? (sizeCol.values[i] as number)
-                : 1;
+            const sizeValue = readSize(sizeCol, i);
             const { colorValue, colorLabel } = readColor(chart, colorCol, i);
             insertRow(
                 chart,
@@ -556,7 +596,12 @@ export function finalizeTree(chart: TreeChartBase): void {
             }
         } else {
             if (firstChild[id] === NULL_NODE) {
-                value[id] = Math.max(0, size[id]);
+                // NOT `Math.max(0, x)`: that maps NaN → NaN, and one NaN
+                // leaf would poison every ancestor sum (dropping whole
+                // subtrees in `squarify`'s `value > 0` filter). The
+                // comparison form maps NaN → 0.
+                const s = size[id];
+                value[id] = s > 0 ? s : 0;
             } else {
                 let sum = 0;
                 for (

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

@@ -225,7 +225,9 @@ export function renderHeatmapFrame(
         drawCellsInstanced(chart, gl, glManager, 0, chart._uploadedCells);
     });
 
-    renderHeatmapChromeOverlay(chart);
+    // Deferred past the GPU fence (see `_defer2D`) so the chrome canvas
+    // doesn't present ahead of the GL cells on resize.
+    chart._defer2D(() => renderHeatmapChromeOverlay(chart));
 }
 
 function ensureProgram(
@@ -650,7 +652,9 @@ function renderFacetedHeatmap(
         });
     }
 
-    renderHeatmapChromeOverlay(chart);
+    // Deferred past the GPU fence (see `_defer2D`) so the chrome canvas
+    // doesn't present ahead of the GL cells on resize.
+    chart._defer2D(() => renderHeatmapChromeOverlay(chart));
 }
 
 /**

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

@@ -187,7 +187,8 @@ export class AreaGlyph {
 
     /**
      * Bind persistent strip buffers and dispatch one TRIANGLE_STRIP per
-     * series-run. Skips hidden series.
+     * series-run. Skips hidden series. `splitFilter` (faceted frames)
+     * draws only the series whose `splitIdx` matches.
      */
     draw(
         chart: SeriesChart,
@@ -196,6 +197,7 @@ export class AreaGlyph {
         projLeft: Float32Array,
         projRight: Float32Array,
         opacity: number,
+        splitFilter?: number,
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -212,6 +214,13 @@ export class AreaGlyph {
                 continue;
             }
 
+            if (
+                splitFilter !== undefined &&
+                chart._series[s.seriesId].splitIdx !== splitFilter
+            ) {
+                continue;
+            }
+
             gl.uniformMatrix4fv(
                 cache.u_projection,
                 false,

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

@@ -30,13 +30,20 @@ type GL = WebGL2RenderingContext | WebGLRenderingContext;
 /**
  * Draw the bar-typed subset of `chart._bars` as instanced quads. Assumes
  * the caller has already `useProgram`'d the bar shader and set uniforms.
+ *
+ * `range` draws a contiguous instance sub-range instead of the full
+ * uploaded set — the faceted renderer uploads instances split-major
+ * (see `uploadBarInstances`) and dispatches one range per facet.
  */
 export function drawBars(
     chart: SeriesChart,
     gl: GL,
     glManager: WebGLContextManager,
+    range?: { start: number; count: number },
 ): void {
-    if (chart._uploadedBars === 0) {
+    const first = range?.start ?? 0;
+    const count = range?.count ?? chart._uploadedBars;
+    if (chart._uploadedBars === 0 || count === 0) {
         return;
     }
 
@@ -62,6 +69,7 @@ export function drawBars(
             loc.a_x_center,
             "bar_x",
             1,
+            first,
         ) &&
         bindInstancedFloatAttr(
             glManager,
@@ -69,15 +77,31 @@ export function drawBars(
             loc.a_half_width,
             "bar_hw",
             1,
+            first,
+        ) &&
+        bindInstancedFloatAttr(
+            glManager,
+            instancing,
+            loc.a_y0,
+            "bar_y0",
+            1,
+            first,
+        ) &&
+        bindInstancedFloatAttr(
+            glManager,
+            instancing,
+            loc.a_y1,
+            "bar_y1",
+            1,
+            first,
         ) &&
-        bindInstancedFloatAttr(glManager, instancing, loc.a_y0, "bar_y0", 1) &&
-        bindInstancedFloatAttr(glManager, instancing, loc.a_y1, "bar_y1", 1) &&
         bindInstancedFloatAttr(
             glManager,
             instancing,
             loc.a_color,
             "bar_color",
             3,
+            first,
         ) &&
         bindInstancedFloatAttr(
             glManager,
@@ -85,6 +109,7 @@ export function drawBars(
             loc.a_series_id,
             "bar_sid",
             1,
+            first,
         ) &&
         bindInstancedFloatAttr(
             glManager,
@@ -92,15 +117,11 @@ export function drawBars(
             loc.a_axis,
             "bar_axis",
             1,
+            first,
         );
 
     if (ok) {
-        instancing.drawArraysInstanced(
-            gl.TRIANGLE_STRIP,
-            0,
-            4,
-            chart._uploadedBars,
-        );
+        instancing.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, count);
     }
 
     setDivisor(loc.a_x_center, 0);

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

@@ -271,7 +271,8 @@ export class LineGlyph {
      * Bind the persistent vertex buffers and dispatch one instanced draw
      * per series. Skips hidden series via `_hiddenSeries`. Gap /
      * transparency rendering is governed by `u_interp_alpha`, set per
-     * series.
+     * series. `splitFilter` (faceted frames) draws only the series
+     * whose `splitIdx` matches — one call per facet.
      */
     draw(
         chart: SeriesChart,
@@ -279,6 +280,7 @@ export class LineGlyph {
         glManager: WebGLContextManager,
         projLeft: Float32Array,
         projRight: Float32Array,
+        splitFilter?: number,
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -310,6 +312,13 @@ export class LineGlyph {
                 continue;
             }
 
+            if (
+                splitFilter !== undefined &&
+                chart._series[s.seriesId].splitIdx !== splitFilter
+            ) {
+                continue;
+            }
+
             gl.uniformMatrix4fv(
                 cache.u_projection,
                 false,

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) instead draws each matching series' contiguous
+     * bucket sub-range — one `drawArrays(POINTS, first, count)` per
+     * series of the facet.
      */
     draw(
         chart: SeriesChart,
@@ -249,6 +278,7 @@ export class ScatterGlyph {
         glManager: WebGLContextManager,
         projLeft: Float32Array,
         projRight: Float32Array,
+        splitFilter?: number,
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -267,6 +297,28 @@ export class ScatterGlyph {
             chart._pluginConfig.point_size_px * dpr,
         );
 
+        if (splitFilter !== undefined) {
+            for (const r of buf.seriesRanges) {
+                if (chart._series[r.seriesId].splitIdx !== splitFilter) {
+                    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 +361,7 @@ function drawBucket(
     colBuf: WebGLBuffer,
     count: number,
     proj: Float32Array,
+    first = 0,
 ): void {
     if (count === 0) {
         return;
@@ -324,5 +377,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) {