@perspective-dev/viewer-charts 5.0.0 → 5.2.0

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

@@ -26,6 +26,30 @@ export interface ChartTypeConfig {
      * sunburst). See {@link PluginConfig} for field semantics.
      */
     applicable_plugin_fields: readonly PluginConfigField[];
+    /**
+     * What `group_by` DRAWS in this chart, e.g. `"X Axis"` for the
+     * Y-series charts. Omitted where the field has no visual role of
+     * its own and is a plain aggregation key — the X/Y and map charts,
+     * whose axes both come from `columns`.
+     *
+     * The `group_by` counterpart of `initial.names`: one declaration
+     * says what every view field draws, so the settings UI's labels and
+     * the agent's `list_plugins` contract read the same source instead
+     * of restating the mapping.
+     */
+    group_by_role?: string;
+    /** What `split_by` DRAWS in this chart. See {@link group_by_role}. */
+    split_by_role?: string;
+    /**
+     * Set on the charts that CONNECT their points in row order, so the
+     * view's row order shows up in the drawing: without a `sort` the
+     * line follows the table's natural order, which reads as a tangle
+     * unless the rows already arrive ordered along the X axis. The point
+     * charts (scatter, density) are unaffected, and a pre-ordered table
+     * needs no `sort` — which is why this is declared per chart rather
+     * than inferred from an empty `sort`.
+     */
+    connects_row_order?: boolean;
     /**
      * Per-chart-type overrides for `DEFAULT_PLUGIN_CONFIG`. Used when a
      * field's sensible default differs by chart family — currently

package/dist/esm/plugin/plugin.d.ts

@@ -25,6 +25,15 @@ export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement
      * resolved values in the `InitMsg`.
      */
     private _pluginConfigStore;
+    /**
+     * Per-column config (`alt_axis`, `chart_type`, formats, …), held on
+     * the element for the same reason as `_pluginConfigStore`: the host
+     * calls `restore()` BEFORE the first draw builds the renderer, so
+     * forwarding only to a live renderer silently drops the initial
+     * `columns_config` — `_buildRenderer` ships it in the `InitMsg`
+     * instead.
+     */
+    private _columnsConfig;
     private get _pluginConfig();
     private set _pluginConfig(value);
     private _effectiveDefaults;

package/dist/esm/transport/protocol.d.ts

@@ -104,6 +104,14 @@ export interface InitMsg {
      * a `setPluginConfig` control msg.
      */
     pluginConfig: PluginConfig;
+    /**
+     * Initial per-column config (`alt_axis`, `chart_type`, formats, …).
+     * Seeds the chart impl before the first `loadAndRender` — the host
+     * calls `plugin.restore` before the renderer exists, so without
+     * this the initial `columns_config` never reaches the worker.
+     * Later changes arrive as `setColumnsConfig` control msgs.
+     */
+    columnsConfig?: Record<string, any>;
     defaultChartType?: string;
     /**
      * Pre-resolved CSS-variable theme snapshot from the host.

package/dist/esm/transport/renderer-transport.d.ts

@@ -133,6 +133,7 @@ export declare class RendererTransport {
         chrome: HTMLCanvasElement;
         facetConfig: FacetConfig;
         pluginConfig: PluginConfig;
+        columnsConfig?: Record<string, any>;
         defaultChartType?: string;
         renderBlitMode: "blit" | "direct";
     }): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perspective-dev/viewer-charts",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Perspective.js WebGL Plugin",
   "unpkg": "./dist/cdn/perspective-viewer-charts.js",
   "jsdelivr": "./dist/cdn/perspective-viewer-charts.js",

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

@@ -188,7 +188,9 @@ export class AreaGlyph {
     /**
      * Bind persistent strip buffers and dispatch one TRIANGLE_STRIP per
      * series-run. Skips hidden series. `splitFilter` (faceted frames)
-     * draws only the series whose `splitIdx` matches.
+     * draws only the series whose `splitIdx` matches; `aggRange` (mixed
+     * glyph-run frames) only those whose `aggIdx` lies in the inclusive
+     * run span.
      */
     draw(
         chart: SeriesChart,
@@ -198,6 +200,7 @@ export class AreaGlyph {
         projRight: Float32Array,
         opacity: number,
         splitFilter?: number,
+        aggRange?: { start: number; end: number },
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -221,6 +224,14 @@ export class AreaGlyph {
                 continue;
             }
 
+            const aggIdx = chart._series[s.seriesId].aggIdx;
+            if (
+                aggRange !== undefined &&
+                (aggIdx < aggRange.start || aggIdx > aggRange.end)
+            ) {
+                continue;
+            }
+
             gl.uniformMatrix4fv(
                 cache.u_projection,
                 false,

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

@@ -272,7 +272,9 @@ export class LineGlyph {
      * per series. Skips hidden series via `_hiddenSeries`. Gap /
      * transparency rendering is governed by `u_interp_alpha`, set per
      * series. `splitFilter` (faceted frames) draws only the series
-     * whose `splitIdx` matches — one call per facet.
+     * whose `splitIdx` matches — one call per facet. `aggRange` (mixed
+     * glyph-run frames) draws only the series whose `aggIdx` lies in
+     * the inclusive run span.
      */
     draw(
         chart: SeriesChart,
@@ -281,6 +283,7 @@ export class LineGlyph {
         projLeft: Float32Array,
         projRight: Float32Array,
         splitFilter?: number,
+        aggRange?: { start: number; end: number },
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -319,6 +322,14 @@ export class LineGlyph {
                 continue;
             }
 
+            const aggIdx = chart._series[s.seriesId].aggIdx;
+            if (
+                aggRange !== undefined &&
+                (aggIdx < aggRange.start || aggIdx > aggRange.end)
+            ) {
+                continue;
+            }
+
             gl.uniformMatrix4fv(
                 cache.u_projection,
                 false,

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

@@ -268,9 +268,9 @@ export class ScatterGlyph {
     /**
      * Bind the persistent left/right buffers and issue up to two draw
      * 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.
+     * (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,
@@ -279,6 +279,7 @@ export class ScatterGlyph {
         projLeft: Float32Array,
         projRight: Float32Array,
         splitFilter?: number,
+        aggRange?: { start: number; end: number },
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -297,9 +298,20 @@ export class ScatterGlyph {
             chart._pluginConfig.point_size_px * dpr,
         );
 
-        if (splitFilter !== undefined) {
+        if (splitFilter !== undefined || aggRange !== undefined) {
             for (const r of buf.seriesRanges) {
-                if (chart._series[r.seriesId].splitIdx !== splitFilter) {
+                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;
                 }
 

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

@@ -47,8 +47,9 @@ 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
@@ -153,96 +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,
-        splitFilter,
-    );
+    // 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,
-            splitFilter,
-        );
+                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;
-        const P = chart._splitPrefixes.length;
-        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;
+        }
 
-            if (splitFilter !== undefined && sid[i] % P !== splitFilter) {
-                continue;
-            }
+        if (hidden.has(sid[i])) {
+            continue;
+        }
 
-            const xc = xC[i];
-            const halfW = hw[i];
-            if (dataX < xc - halfW || dataX > xc + halfW) {
+        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,
-            splitFilter,
-        );
-        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(
@@ -255,6 +291,7 @@ function hitTestPoints(
     pxPerDataYLeft: number,
     pxPerDataYRight: number,
     splitFilter?: number,
+    aggRange?: { start: number; end: number },
 ): SeriesChartRecord | null {
     const N = chart._numCategories;
     const S = chart._series.length;
@@ -283,6 +320,13 @@ function hitTestPoints(
             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;
 
@@ -340,6 +384,7 @@ function hitTestAreas(
     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.
@@ -382,6 +427,13 @@ function hitTestAreas(
             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];
@@ -406,6 +458,13 @@ function hitTestAreas(
             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;