@perspective-dev/viewer-charts 4.3.0

package/dist/esm/charts/series/glyphs/draw-scatter.d.ts

@@ -0,0 +1,33 @@
+import type { WebGLContextManager } from "../../../webgl/context-manager";
+import type { SeriesChart } from "../series";
+type GL = WebGL2RenderingContext | WebGLRenderingContext;
+/**
+ * Scatter glyph for {@link SeriesChart}. Owns the program + per-axis
+ * (position, color) GPU buffers. Single program/buffer set; left and
+ * right axes are merged into shared buffers with sub-ranges.
+ */
+export declare class ScatterGlyph {
+    private _program;
+    private _buffers;
+    private ensureProgram;
+    /**
+     * Drop persistent scatter buffer state. The underlying GL buffer
+     * objects on `_program` are reused (owned by the program cache,
+     * not the per-build buffer view).
+     */
+    invalidateBuffers(_chart: SeriesChart): void;
+    /**
+     * Build merged per-axis (position, color) buffers for every visible
+     * scatter series and upload them. Hidden series are excluded — call
+     * this from data-load and from the legend-toggle path so the GPU
+     * buffers always reflect the current visible mask.
+     */
+    rebuildBuffers(chart: SeriesChart, glManager: WebGLContextManager): void;
+    /**
+     * Bind the persistent left/right buffers and issue up to two draw
+     * calls. No per-frame allocations or buffer uploads.
+     */
+    draw(chart: SeriesChart, gl: GL, glManager: WebGLContextManager, projLeft: Float32Array, projRight: Float32Array): void;
+    destroy(chart: SeriesChart): void;
+}
+export {};

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

@@ -0,0 +1,228 @@
+import type { ColumnDataMap } from "../../data/view-reader";
+import type { CategoricalLevel } from "../../axis/categorical-axis";
+import { type AxisMode, type NumericCategoryDomain } from "../common/category-axis-resolver";
+import { type ChartType, type ColumnChartConfig } from "./series-type";
+export interface SeriesInfo {
+    seriesId: number;
+    aggIdx: number;
+    splitIdx: number;
+    aggName: string;
+    splitKey: string;
+    label: string;
+    color: [number, number, number];
+    axis: 0 | 1;
+    chartType: ChartType;
+    stack: boolean;
+}
+/**
+ * Logical bar/area record. Synthesized on demand from {@link BarColumns}
+ * via {@link readBarRecord} for tooltip / hover paths. The pipeline never
+ * materializes these — see `BarColumns` for the columnar storage that
+ * replaces the legacy `SeriesChartRecord[]`.
+ */
+export interface SeriesChartRecord {
+    catIdx: number;
+    aggIdx: number;
+    splitIdx: number;
+    seriesId: number;
+    xCenter: number;
+    halfWidth: number;
+    y0: number;
+    y1: number;
+    value: number;
+    axis: 0 | 1;
+    /**
+     * `"bar"` quads or `"area"` strip segments both stack via this record.
+     */
+    chartType: "bar" | "area";
+}
+export declare const BAR_TYPE_BAR = 0;
+export declare const BAR_TYPE_AREA = 1;
+/**
+ * Columnar storage for the bar/area record set. Replaces the legacy
+ * `SeriesChartRecord[]` to avoid per-record POJO allocation at scale —
+ * with N×M×P potentially in the millions, the array-of-objects layout
+ * was the dominant build-time GC pressure.
+ *
+ * Records are appended in `(catIdx, aggIdx, splitIdx)` lexicographic
+ * order — the outer category loop guarantees `catIdx` is monotonically
+ * non-decreasing, which the renderer / hit-test use for binary-search
+ * narrowing.
+ *
+ * `count` is the active record count; the underlying typed arrays may
+ * be over-allocated for capacity reuse across builds.
+ */
+/**
+ * Compact columnar storage for the bar/area record set.
+ *
+ * Three fields the prior schema carried have been dropped because
+ * they're cheaply derivable at hover time:
+ *   - `aggIdx`    ← `seriesId / splitCount` (integer division)
+ *   - `splitIdx`  ← `seriesId % splitCount`
+ *   - `value`     ← `samples[catIdx * S + seriesId]`
+ *
+ * Per-cell write count drops from 11 to 8 (~27% fewer typed-array
+ * stores) and per-record memory drops from 58 B to 42 B (~28% lower
+ * footprint at scale). `chartType` is kept (1 B / record) — it's
+ * read in tight loops in the render and hit-test paths and a string
+ * dispatch via `_series[]` would be slower than the byte compare.
+ */
+export interface BarColumns {
+    count: number;
+    catIdx: Int32Array;
+    seriesId: Int32Array;
+    /**
+     * 0 = left axis, 1 = right axis.
+     */
+    axis: Uint8Array;
+    /**
+     * {@link BAR_TYPE_BAR} | {@link BAR_TYPE_AREA}.
+     */
+    chartType: Uint8Array;
+    xCenter: Float64Array;
+    halfWidth: Float64Array;
+    y0: Float64Array;
+    y1: Float64Array;
+}
+export declare function emptyBarColumns(): BarColumns;
+/**
+ * Reuse `prev`'s typed arrays when capacity is sufficient, else allocate
+ * fresh. Resets `count` to 0 either way; pipeline writes from index 0.
+ */
+export declare function ensureBarColumnsCapacity(prev: BarColumns | null, capacity: number): BarColumns;
+/**
+ * Synthesize a {@link SeriesChartRecord} POJO for record `i`. Used by
+ * tooltip / hover paths that hand out a single record reference; not
+ * called in any frame-rate hot loop.
+ *
+ * `splitCount` is `splitPrefixes.length` from the build result (= `P`
+ * in pipeline notation). `samples` + `numSeries` recover the raw
+ * value from the unstacked sample grid; `samples[catIdx * S + sid]`
+ * always carries the same value the pipeline saw when emitting the
+ * record (both writes share the same `v` source).
+ */
+export declare function readBarRecord(cols: BarColumns, i: number, splitCount: number, samples: Float32Array, numSeries: number): SeriesChartRecord;
+/**
+ * Reusable Float64 scratch — chart owns one for `posStack` and one for
+ * `negStack`. Pipeline zero-fills the active prefix on entry.
+ */
+export declare function ensureFloat64Scratch(prev: Float64Array | null, capacity: number): Float64Array;
+export interface SeriesPipelineInput {
+    columns: ColumnDataMap;
+    numRows: number;
+    columnSlots: (string | null)[];
+    groupBy: string[];
+    splitBy: string[];
+    /**
+     * Source-column types for `group_by` columns (table.schema() merged
+     * with view.expression_schema()). Used to (a) stringify non-string
+     * row-path levels and (b) decide between category and numeric axis
+     * mode for single-level group_bys.
+     */
+    groupByTypes: Record<string, string>;
+    columnsConfig: Record<string, ColumnChartConfig> | undefined;
+    /**
+     * Plugin-scoped default glyph when a column has no explicit entry.
+     */
+    defaultChartType?: ChartType;
+    /**
+     * Plugin-config knobs consumed by the build pipeline. Pulled from
+     * the chart impl's `_pluginConfig` (sourced from the host's
+     * `plugin_config_schema` / `restore({ plugin_config })`):
+     *
+     *  - `autoAltYAxis` — auto-split aggregates onto a secondary Y
+     *    axis when their magnitude ratio exceeds
+     *    `DUAL_Y_RATIO_THRESHOLD`. Replaces the `AUTO_ALT_Y_AXIS`
+     *    compile-time toggle.
+     *  - `bandInnerFrac` / `barInnerPad` — band-slot geometry forwarded
+     *    to `computeSlotGeometry`. Replace the `BAND_INNER_FRAC` /
+     *    `BAR_INNER_PAD` constants.
+     */
+    autoAltYAxis: boolean;
+    bandInnerFrac: number;
+    barInnerPad: number;
+    /**
+     * Anchor value-axis extents to zero. When `true` (bar / area
+     * default), `leftDomain` / `rightDomain` are guaranteed to enclose
+     * `0` so bars and areas render against their natural baseline.
+     * When `false` (line / scatter default), the domain is the raw
+     * `min`/`max` of the data — the axis tightens around the visible
+     * variation. Maps directly to `PluginConfig.include_zero`.
+     */
+    includeZero: boolean;
+    /**
+     * Reusable scratch — pipeline writes records into these in place
+     * and zero-fills the stack ladder. Pass the previous build's
+     * outputs to amortize allocation across data reloads.
+     */
+    scratchBars?: BarColumns | null;
+    scratchPosStack?: Float64Array | null;
+    scratchNegStack?: Float64Array | null;
+}
+export type { NumericCategoryDomain };
+export interface SeriesPipelineResult {
+    aggregates: string[];
+    splitPrefixes: string[];
+    rowPaths: CategoricalLevel[];
+    numCategories: number;
+    rowOffset: number;
+    /**
+     * Axis mode discriminator. `category` is the default (zero or
+     * many group_by levels, or a single string/boolean level). `numeric`
+     * fires for a single non-string non-boolean group_by — bars are
+     * positioned by the underlying data value rather than logical
+     * category index.
+     */
+    axisMode: AxisMode;
+    /**
+     * Populated only when `axisMode.mode === "numeric"`.
+     */
+    numericCategoryDomain: NumericCategoryDomain | null;
+    /**
+     * Per-category X coordinate in real data units. Populated only in
+     * numeric axis mode — `null` in category mode where catIdx itself
+     * is the position. Indexed by `catIdx` (0..numCategories-1).
+     */
+    categoryPositions: Float64Array | null;
+    series: SeriesInfo[];
+    /**
+     * Columnar bar/area records, one per (catIdx, agg, split) for series
+     * where `stack === true && chartType in ["bar", "area"]` (stacked) or
+     * `chartType in ["bar", "area"]` with non-zero value (unstacked).
+     */
+    bars: BarColumns;
+    /**
+     * Reusable scratch passthrough — these own the stack ladder typed
+     * arrays so the next build can reuse capacity.
+     */
+    posStack: Float64Array | null;
+    negStack: Float64Array | null;
+    /**
+     * Unstacked sample grid: `samples[catIdx * S + seriesId]` is the raw
+     * value for that cell. Only valid for non-stacking series (or for
+     * stacking series when you need the raw, pre-stack value); the
+     * corresponding bit in `sampleValid` indicates whether the cell carries
+     * data. `S === series.length`.
+     */
+    samples: Float32Array;
+    sampleValid: Uint8Array;
+    leftDomain: {
+        min: number;
+        max: number;
+    };
+    rightDomain: {
+        min: number;
+        max: number;
+    } | null;
+    hasRightAxis: boolean;
+}
+/**
+ * Pure pipeline: turn a raw `ColumnDataMap` into (a) columnar stacked
+ * bar/area records and (b) an unstacked `samples` grid for line/scatter
+ * glyphs plus non-stacking bar/area series. Holds row_path data as
+ * zero-copy views (no materialization of category strings).
+ *
+ * Automatically splits aggregates across a secondary Y axis when their
+ * extents differ by more than {@link DUAL_Y_RATIO_THRESHOLD}×.
+ */
+export declare function buildSeriesPipeline(input: SeriesPipelineInput): SeriesPipelineResult;

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

@@ -0,0 +1,35 @@
+import type { SeriesChart } from "./series";
+import { type SeriesChartRecord } from "./series-build";
+/**
+ * Unified accessor for the currently hovered glyph. Returns either the
+ * real {@link SeriesChartRecord} from `_bars` (bar / stacked-area hits) or the
+ * synthetic one stored in `_hoveredSample` (line / scatter / non-stacked
+ * area hits), or `null`.
+ */
+export declare 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.
+ * Updates `_hoveredBarIdx` or `_hoveredSample` and re-renders on change.
+ */
+export declare function handleBarHover(chart: SeriesChart, mx: number, my: number): void;
+/**
+ * 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).
+ */
+export declare function handleBarLegendClick(chart: SeriesChart, mx: number, my: number): boolean;
+/**
+ * Build the per-bar tooltip content lines.
+ */
+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.
+ */
+export declare function formatBarCategoryPath(chart: SeriesChart, catIdx: number): string;
+export declare function showBarPinnedTooltip(chart: SeriesChart, barIdx: number): void;
+/**
+ * Pin a tooltip against a synthetic BarRecord (scatter/line/area hit).
+ */
+export declare function showBarPinnedTooltipForSample(chart: SeriesChart, bar: SeriesChartRecord): void;
+export declare function dismissBarPinnedTooltip(chart: SeriesChart): void;

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

@@ -0,0 +1,41 @@
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import { type SeriesChart } from "./series";
+/**
+ * Upload bar instance buffers from the columnar `_bars` storage. Filters
+ * to bar-typed records only (areas draw as triangle strips). Skips
+ * hidden series. Re-called from data-load and legend-toggle paths; the
+ * scratch buffers and `_visibleBarIndices` are reused across calls.
+ */
+export declare function uploadBarInstances(chart: SeriesChart, glManager: WebGLContextManager): void;
+/**
+ * Re-upload the per-bar color attribute. Short-circuits when the new
+ * colors match the last-uploaded snapshot byte-for-byte. Legacy code
+ * ran this every frame regardless; with the cached palette now stable
+ * across pan/zoom this becomes a no-op except after data load /
+ * `restyle()`.
+ */
+export declare function uploadBarColors(chart: SeriesChart, glManager: WebGLContextManager): void;
+/**
+ * Drop persistent vertex buffers for line / scatter / area glyphs.
+ * Called from `uploadAndRender` before {@link rebuildGlyphBuffers}.
+ */
+export declare function invalidateGlyphBuffers(chart: SeriesChart): void;
+/**
+ * Build persistent vertex buffers for line / scatter / area glyphs.
+ * The legacy renderers rebuilt and re-uploaded these every frame inside
+ * the per-glyph draw functions; with stable post-build geometry the
+ * uploads now happen exactly once per data-load / palette change.
+ */
+export declare function rebuildGlyphBuffers(chart: SeriesChart, glManager: WebGLContextManager): void;
+/**
+ * Full-frame render: gridlines → WebGL bars (instanced) → chrome overlay.
+ */
+export declare function renderBarFrame(chart: SeriesChart, glManager: WebGLContextManager): void;
+/**
+ * Draw axes chrome + legend + tooltip onto the overlay canvas.
+ */
+export declare function renderBarChromeOverlay(chart: SeriesChart): void;
+export declare function rightAxisDataToPixel(chart: SeriesChart, x: number, y: number): {
+    px: number;
+    py: number;
+};

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

@@ -0,0 +1,49 @@
+export type ChartType = "bar" | "line" | "scatter" | "area";
+/**
+ * Per-column entry inside the viewer's `columns_config` map. The map itself
+ * is typed as `Record<string, any>` at the plugin boundary because
+ * `columns_config` is shared across plugins; this interface documents the
+ * keys the Y-bar glyph router consumes.
+ */
+export interface ColumnChartConfig {
+    /**
+     * "Bar" | "Line" | "Scatter" | "Area" (case-insensitive). Invalid / missing → bar.
+     */
+    chart_type?: string;
+    /**
+     * Explicit stack override. If omitted: bar / area stack by default,
+     * line / scatter do not.
+     */
+    stack?: boolean;
+    /**
+     * Force this aggregate onto the secondary (right) Y axis,
+     * independent of `autoAltYAxis` and the dual-axis ratio
+     * heuristic. Missing / false → axis assignment is driven by
+     * `autoAltYAxis` alone.
+     */
+    alt_axis?: boolean;
+}
+/**
+ * Resolve the render glyph for an aggregate base name. Lookup key is the
+ * *base* (e.g. `"Sales"`); composite arrow columns like `"North|Sales"`
+ * should strip the prefix before calling — the bar pipeline already
+ * tracks aggregates as base names, so call sites pass the base directly.
+ *
+ * `fallback` is the plugin's default glyph (e.g. `"line"` for Y Line),
+ * supplied by the plugin element via `setDefaultChartType`. Falls back to
+ * `"bar"` when the plugin never set one.
+ */
+export declare function resolveChartType(aggName: string, cfg: Record<string, ColumnChartConfig> | undefined, fallback?: ChartType): ChartType;
+/**
+ * Resolve whether a series stacks with its aggregate siblings.
+ * Default: `true` for bar/area, `false` for line/scatter. Overridable
+ * per column via `columns_config[aggName].stack`.
+ */
+export declare function resolveStack(aggName: string, chartType: ChartType, cfg: Record<string, ColumnChartConfig> | undefined): boolean;
+/**
+ * Resolve whether a column is pinned to the secondary Y axis via
+ * `columns_config[aggName].alt_axis`. Independent of `autoAltYAxis`:
+ * when `true`, the per-column override forces axis 1 regardless of
+ * the auto-split heuristic.
+ */
+export declare function resolveAltAxis(aggName: string, cfg: Record<string, ColumnChartConfig> | undefined): boolean;