@perspective-dev/viewer-charts 4.3.0 → 4.5.1

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

@@ -16,6 +16,49 @@ import type { WebGLContextManager } from "../../webgl/context-manager";
 import type { CartesianChart, SplitGroup } from "./cartesian";
 import { LabelInterner } from "./label-interner";
 
+/**
+ * Resolve a row's string value into a slot index in `dictionary`,
+ * inserting on first encounter. Invalid / missing values land in a
+ * lazily-added `"(null)"` slot — no reserved slot 0 when the data has
+ * no nulls. Shared by the X and Y categorical paths in
+ * `processCartesianChunk`.
+ */
+function lookupCategorySlot(
+    col: ColumnData | null,
+    rowIdx: number,
+    dictionary: string[],
+    seen: Map<string, number>,
+): number {
+    let label: string;
+    if (!col) {
+        label = "(null)";
+    } else {
+        const valid = col.valid;
+        const isValid = valid
+            ? !!((valid[rowIdx >> 3] >> (rowIdx & 7)) & 1)
+            : true;
+        if (!isValid) {
+            label = "(null)";
+        } else if (col.indices && col.dictionary) {
+            label = col.dictionary[col.indices[rowIdx]] ?? "(null)";
+        } else if (col.values) {
+            const v = col.values[rowIdx];
+            label = v == null ? "(null)" : String(v);
+        } else {
+            label = "(null)";
+        }
+    }
+
+    let slot = seen.get(label);
+    if (slot === undefined) {
+        slot = dictionary.length;
+        dictionary.push(label);
+        seen.set(label, slot);
+    }
+
+    return slot;
+}
+
 /**
  * Resolve per-split-prefix column-name tuples. `colorBase`/`sizeBase`
  * are optional (empty string when the corresponding slot is unset).
@@ -122,6 +165,41 @@ export function initCartesianPipeline(
     chart._yLabel = yBase;
     chart._xIsRowIndex = !xBase;
 
+    // Post-aggregation `string` columns on X / Y switch the axis to
+    // categorical: per-row slot indices are written into `_xData` /
+    // `_yData` instead of raw values, and the chrome overlay paints a
+    // categorical axis. Reset the per-frame dictionary state here at
+    // chunk 0 so slot 0 is always the first non-null label encountered
+    // in arrival order (matching the perspective view's sort).
+    chart._xIsString = !!xBase && chart._columnTypes[xBase] === "string";
+    chart._yIsString = !!yBase && chart._columnTypes[yBase] === "string";
+    chart._xCategoryDictionary = [];
+    chart._yCategoryDictionary = [];
+    chart._xCategorySeen = new Map();
+    chart._yCategorySeen = new Map();
+    chart._xCategoryDomain = null;
+    chart._yCategoryDomain = null;
+
+    // Categorical axes use 0-based slot indices, so the rebase origin
+    // is fixed at 0. Skipping the NaN-init guard below prevents the
+    // first-seen-slot from being adopted as the origin (which would
+    // shift every other slot's pixel position).
+    if (chart._xIsString) {
+        chart._xOrigin = 0;
+        chart._xMin = 0;
+        chart._xMax = 0;
+        chart._expandedXMin = Infinity;
+        chart._expandedXMax = -Infinity;
+    }
+
+    if (chart._yIsString) {
+        chart._yOrigin = 0;
+        chart._yMin = 0;
+        chart._yMax = 0;
+        chart._expandedYMin = Infinity;
+        chart._expandedYMax = -Infinity;
+    }
+
     // Capture the per-series row budget BEFORE any split expansion. When
     // split_by is active we grow `totalCapacity` to fit `numSplits`
     // parallel slot ranges; reading `totalCapacity` again after that
@@ -245,9 +323,16 @@ export function processCartesianChunk(
     // carries the user's selected color column. The color-resolution
     // logic in the inner loop reads uniformly from `ser.colorCol`
     // across both modes.
+    //
+    // `xColData` / `yColData` carry the full `ColumnData` so the
+    // categorical path can read `indices` + `dictionary` for slot
+    // lookup; `xCol` / `yCol` keep the numeric fast path zero-cost
+    // (and stay `null` on string columns where `values` is unset).
     type SeriesSrc = {
         xCol: Float32Array | Float64Array | Int32Array | null;
-        yCol: Float32Array | Float64Array | Int32Array;
+        yCol: Float32Array | Float64Array | Int32Array | null;
+        xColData: ColumnData | null;
+        yColData: ColumnData | null;
         xValid: Uint8Array | undefined;
         yValid: Uint8Array | undefined;
         colorCol: ColumnData | null;
@@ -260,7 +345,11 @@ export function processCartesianChunk(
         for (const sg of chart._splitGroups) {
             const xc = sg.xColName ? columns.get(sg.xColName) : null;
             const yc = columns.get(sg.yColName);
-            if (!yc?.values) {
+            if (!yc) {
+                continue;
+            }
+
+            if (!chart._yIsString && !yc.values) {
                 continue;
             }
 
@@ -273,7 +362,9 @@ export function processCartesianChunk(
                 : null;
             series.push({
                 xCol: xc?.values ?? null,
-                yCol: yc.values,
+                yCol: yc.values ?? null,
+                xColData: xc ?? null,
+                yColData: yc,
                 xValid: xc?.valid,
                 yValid: yc.valid,
                 colorCol: cc,
@@ -284,7 +375,11 @@ export function processCartesianChunk(
     } else {
         const xc = chart._xName ? columns.get(chart._xName) : null;
         const yc = chart._yName ? columns.get(chart._yName) : null;
-        if (!yc?.values) {
+        if (!yc) {
+            return;
+        }
+
+        if (!chart._yIsString && !yc.values) {
             return;
         }
 
@@ -296,7 +391,9 @@ export function processCartesianChunk(
             : null;
         series.push({
             xCol: xc?.values ?? null,
-            yCol: yc.values,
+            yCol: yc.values ?? null,
+            xColData: xc ?? null,
+            yColData: yc,
             xValid: xc?.valid,
             yValid: yc?.valid,
             colorCol: cc,
@@ -386,11 +483,20 @@ export function processCartesianChunk(
         let writeIdx = 0;
         for (let j = 0; j < sourceLength && writeIdx < maxWrite; j++) {
             const i = j;
-            if (ser.yValid && !((ser.yValid[i >> 3] >> (i & 7)) & 1)) {
+            // Numeric axes filter out null/invalid rows entirely;
+            // categorical axes route them into a `"(null)"` slot
+            // instead, so the validity / NaN guards only apply on
+            // the numeric branch.
+            if (
+                !chart._yIsString &&
+                ser.yValid &&
+                !((ser.yValid[i >> 3] >> (i & 7)) & 1)
+            ) {
                 continue;
             }
 
             if (
+                !chart._xIsString &&
                 ser.xCol &&
                 ser.xValid &&
                 !((ser.xValid[i >> 3] >> (i & 7)) & 1)
@@ -402,12 +508,40 @@ export function processCartesianChunk(
                 colorValid !== undefined &&
                 !((colorValid[i >> 3] >> (i & 7)) & 1);
 
-            const rawY = ser.yCol[i] as number;
-            const rawX = ser.xCol ? (ser.xCol[i] as number) : startRow + i;
-            if (isNaN(rawX) || isNaN(rawY)) {
+            let rawY: number;
+            if (chart._yIsString) {
+                rawY = lookupCategorySlot(
+                    ser.yColData,
+                    i,
+                    chart._yCategoryDictionary,
+                    chart._yCategorySeen,
+                );
+            } else if (ser.yCol) {
+                rawY = ser.yCol[i] as number;
+                if (isNaN(rawY)) {
+                    continue;
+                }
+            } else {
                 continue;
             }
 
+            let rawX: number;
+            if (chart._xIsString) {
+                rawX = lookupCategorySlot(
+                    ser.xColData,
+                    i,
+                    chart._xCategoryDictionary,
+                    chart._xCategorySeen,
+                );
+            } else if (ser.xCol) {
+                rawX = ser.xCol[i] as number;
+                if (isNaN(rawX)) {
+                    continue;
+                }
+            } else {
+                rawX = startRow + i;
+            }
+
             // Project raw (x, y) → data-space (x, y). Default is
             // identity for cartesian charts; map subclasses override
             // to apply Mercator. Second NaN guard catches projection

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

@@ -34,7 +34,6 @@ import { renderCanvasTooltip } from "../../interaction/tooltip-controller";
 import {
     computeTicks,
     renderGridlines,
-    renderAxesChrome,
     renderCellXAxis,
     renderCellYAxis,
     renderOuterXAxis,
@@ -42,6 +41,14 @@ import {
     type AxisDomain,
 } from "../../axis/numeric-axis";
 import { initCanvas, getScaledContext } from "../../axis/canvas";
+import {
+    type CategoricalDomain,
+    type CategoricalLevel,
+    measureCategoricalAxisHeight,
+    measureCategoricalAxisWidth,
+    renderCategoricalXTicks,
+    renderCategoricalYTicks,
+} from "../../axis/categorical-axis";
 import {
     renderLegend,
     renderLegendAt,
@@ -240,6 +247,88 @@ function buildYDomain(
     };
 }
 
+/**
+ * Wrap a value-axis dictionary into the single-level `CategoricalDomain`
+ * the categorical axis painter expects. Caches by reference identity on
+ * the chart so chrome-overlay redraws on hover don't rebuild the domain.
+ */
+function buildCategoricalDomainFromDict(
+    dictionary: string[],
+    label: string,
+): CategoricalDomain {
+    let maxLabelChars = 0;
+    for (const s of dictionary) {
+        if (s.length > maxLabelChars) {
+            maxLabelChars = s.length;
+        }
+    }
+
+    const level: CategoricalLevel = {
+        labels: dictionary.slice(),
+        runs: [],
+        maxLabelChars,
+    };
+    return {
+        levels: [level],
+        numRows: dictionary.length,
+        levelLabels: [label],
+    };
+}
+
+/**
+ * Dispatch each axis side to the categorical painter when its source
+ * column is post-aggregation `string`-typed, or to the numeric painter
+ * otherwise. Used by both single-plot and faceted (per-cell) chrome
+ * overlays.
+ */
+function renderCartesianCellAxes(
+    chart: CartesianChart,
+    canvas: Canvas2D,
+    layout: PlotLayout,
+    xDomain: AxisDomain,
+    yDomain: AxisDomain,
+    xTicks: number[],
+    yTicks: number[],
+    theme: Theme,
+    dpr: number,
+): void {
+    if (chart._xIsString && chart._xCategoryDomain) {
+        const ctx = getScaledContext(canvas, dpr);
+        if (ctx) {
+            renderCategoricalXTicks(ctx, layout, chart._xCategoryDomain, theme);
+        }
+    } else {
+        renderCellXAxis(
+            canvas,
+            xDomain,
+            layout,
+            xTicks,
+            theme,
+            true,
+            dpr,
+            chart.getColumnFormatter(chart._xName, "tick"),
+        );
+    }
+
+    if (chart._yIsString && chart._yCategoryDomain) {
+        const ctx = getScaledContext(canvas, dpr);
+        if (ctx) {
+            renderCategoricalYTicks(ctx, layout, chart._yCategoryDomain, theme);
+        }
+    } else {
+        renderCellYAxis(
+            canvas,
+            yDomain,
+            layout,
+            yTicks,
+            theme,
+            true,
+            dpr,
+            chart.getColumnFormatter(chart._yName, "tick"),
+        );
+    }
+}
+
 /**
  * Original single-plot render path — all series drawn into one
  * `PlotLayout` with one projection matrix. Used when splits are absent
@@ -255,10 +344,42 @@ function renderSinglePlotFrame(
     const gl = glManager.gl;
     const { cssWidth, cssHeight, xIsDate, yIsDate, hasColorCol } = ctx;
 
+    // Materialize per-axis categorical domains from the build-pass
+    // dictionaries before measuring gutters — the leaf-rotation budget
+    // in `measureCategoricalAxisHeight` depends on `maxLabelChars`.
+    chart._xCategoryDomain =
+        chart._xIsString && chart._xCategoryDictionary.length > 0
+            ? buildCategoricalDomainFromDict(
+                  chart._xCategoryDictionary,
+                  chart._xLabel || chart._xName || "",
+              )
+            : null;
+    chart._yCategoryDomain =
+        chart._yIsString && chart._yCategoryDictionary.length > 0
+            ? buildCategoricalDomainFromDict(
+                  chart._yCategoryDictionary,
+                  chart._yLabel || chart._yName || "",
+              )
+            : null;
+
+    // One-pass plot-width / plot-height estimate to size the
+    // categorical gutter overrides; same approach as series-render.
+    const estRight = hasColorCol ? 80 : 16;
+    const estLeftPlain = 55 + (chart._yLabel ? 16 : 0);
+    const estPlotWidth = Math.max(1, cssWidth - estLeftPlain - estRight);
+    const leftExtra = chart._yCategoryDomain
+        ? measureCategoricalAxisWidth(chart._yCategoryDomain)
+        : undefined;
+    const bottomExtra = chart._xCategoryDomain
+        ? measureCategoricalAxisHeight(chart._xCategoryDomain, estPlotWidth)
+        : undefined;
+
     const layout = new PlotLayout(cssWidth, cssHeight, {
         hasXLabel: !!chart._xLabel,
         hasYLabel: !!chart._yLabel,
         hasLegend: hasColorCol,
+        leftExtra,
+        bottomExtra,
     });
     chart._lastLayout = layout;
     if (chart._zoomController) {
@@ -279,7 +400,9 @@ function renderSinglePlotFrame(
 
     const xDomain = buildXDomain(chart, domain.xMin, domain.xMax, xIsDate);
     const yDomain = buildYDomain(chart, domain.yMin, domain.yMax, yIsDate);
-    const { xTicks, yTicks } = computeTicks(xDomain, yDomain, layout);
+    const numericTicks = computeTicks(xDomain, yDomain, layout);
+    const xTicks = chart._xIsString ? [] : numericTicks.xTicks;
+    const yTicks = chart._yIsString ? [] : numericTicks.yTicks;
 
     const isMap = chart._renderMode === "map";
 
@@ -349,6 +472,26 @@ function renderFacetedFrame(
     const gl = glManager.gl;
     const { cssWidth, cssHeight, xIsDate, yIsDate } = ctx;
 
+    // Materialize per-axis categorical domains (shared across facets:
+    // the build dictionary is global, so slot N refers to the same
+    // string in every cell). Faceted layout still uses the default
+    // per-cell gutters from `buildFacetGrid` — rotated leaf labels in
+    // tight cells may overflow but won't crash.
+    chart._xCategoryDomain =
+        chart._xIsString && chart._xCategoryDictionary.length > 0
+            ? buildCategoricalDomainFromDict(
+                  chart._xCategoryDictionary,
+                  chart._xLabel || chart._xName || "",
+              )
+            : null;
+    chart._yCategoryDomain =
+        chart._yIsString && chart._yCategoryDictionary.length > 0
+            ? buildCategoricalDomainFromDict(
+                  chart._yCategoryDictionary,
+                  chart._yLabel || chart._yName || "",
+              )
+            : null;
+
     const labels = chart._splitGroups.map((g) => g.prefix);
 
     // Legend: reserve space only when the user wired a color column.
@@ -415,11 +558,15 @@ function renderFacetedFrame(
 
     // Gridlines + per-facet axes use the first cell's layout for tick
     // sampling (all cells have identical plotRect dimensions). Per-facet
-    // rendering then reuses the same tick arrays.
+    // rendering then reuses the same tick arrays. Categorical sides
+    // skip numeric tick computation; the categorical painter handles
+    // its own label placement off the dictionary.
     const sampleLayout = grid.cells[0]?.layout;
-    const { xTicks, yTicks } = sampleLayout
+    const numericFacetTicks = sampleLayout
         ? computeTicks(xDomain, yDomain, sampleLayout)
         : { xTicks: [], yTicks: [] };
+    const xTicks = chart._xIsString ? [] : numericFacetTicks.xTicks;
+    const yTicks = chart._yIsString ? [] : numericFacetTicks.yTicks;
 
     // One-shot destructive prep for the gridline + WebGL canvases.
     // Both phases below are per-facet; calling their destructive
@@ -566,17 +713,16 @@ function renderSinglePlotChromeOverlay(chart: CartesianChart): void {
     if (isMap) {
         chart.renderMapChrome(chart._chromeCanvas!, layout, theme, dpr);
     } else {
-        renderAxesChrome(
+        renderCartesianCellAxes(
+            chart,
             chart._chromeCanvas!,
+            layout,
             chart._lastXDomain!,
             chart._lastYDomain!,
-            layout,
             chart._lastXTicks!,
             chart._lastYTicks!,
             theme,
             dpr,
-            chart.getColumnFormatter(chart._xName, "tick"),
-            chart.getColumnFormatter(chart._yName, "tick"),
         );
     }
 
@@ -633,8 +779,13 @@ function renderFacetedChromeOverlay(chart: CartesianChart): void {
     // — these already fold in the independent-zoom override (outer
     // axes are incompatible with per-cell viewports), so `sharedX` /
     // `sharedY` true here implies shared-zoom too.
-    const sharedX = chart._lastEffectiveSharedX;
-    const sharedY = chart._lastEffectiveSharedY;
+    //
+    // Categorical axes additionally force per-cell rendering: the
+    // outer-axis painter is numeric-only and the shared dictionary
+    // already produces the same labels in every cell, so a per-cell
+    // categorical axis is equivalent to a shared one visually.
+    const sharedX = chart._lastEffectiveSharedX && !chart._xIsString;
+    const sharedY = chart._lastEffectiveSharedY && !chart._yIsString;
     const independent = chart._facetConfig.zoom_mode === "independent";
 
     // Shared X axis: one outer band across the bottom of the grid,
@@ -689,29 +840,53 @@ function renderFacetedChromeOverlay(chart: CartesianChart): void {
             : { xTicks: sharedXTicks, yTicks: sharedYTicks };
 
         if (!isMap && !sharedX) {
-            renderCellXAxis(
-                canvas,
-                localX,
-                cell.layout,
-                ticks.xTicks,
-                theme,
-                !!chart._xLabel,
-                dpr,
-                chart.getColumnFormatter(chart._xName, "tick"),
-            );
+            if (chart._xIsString && chart._xCategoryDomain) {
+                const cellCtx = getScaledContext(canvas, dpr);
+                if (cellCtx) {
+                    renderCategoricalXTicks(
+                        cellCtx,
+                        cell.layout,
+                        chart._xCategoryDomain,
+                        theme,
+                    );
+                }
+            } else {
+                renderCellXAxis(
+                    canvas,
+                    localX,
+                    cell.layout,
+                    ticks.xTicks,
+                    theme,
+                    !!chart._xLabel,
+                    dpr,
+                    chart.getColumnFormatter(chart._xName, "tick"),
+                );
+            }
         }
 
         if (!isMap && !sharedY) {
-            renderCellYAxis(
-                canvas,
-                localY,
-                cell.layout,
-                ticks.yTicks,
-                theme,
-                !!chart._yLabel,
-                dpr,
-                chart.getColumnFormatter(chart._yName, "tick"),
-            );
+            if (chart._yIsString && chart._yCategoryDomain) {
+                const cellCtx = getScaledContext(canvas, dpr);
+                if (cellCtx) {
+                    renderCategoricalYTicks(
+                        cellCtx,
+                        cell.layout,
+                        chart._yCategoryDomain,
+                        theme,
+                    );
+                }
+            } else {
+                renderCellYAxis(
+                    canvas,
+                    localY,
+                    cell.layout,
+                    ticks.yTicks,
+                    theme,
+                    !!chart._yLabel,
+                    dpr,
+                    chart.getColumnFormatter(chart._yName, "tick"),
+                );
+            }
         }
 
         if (cell.titleRect) {

package/src/ts/charts/cartesian/cartesian.ts

@@ -16,6 +16,7 @@ import { AbstractChart } from "../chart-base";
 import { SpatialHitTester } from "../../interaction/hit-test";
 import { PlotLayout } from "../../layout/plot-layout";
 import { type AxisDomain } from "../../axis/numeric-axis";
+import type { CategoricalDomain } from "../../axis/categorical-axis";
 import type { GradientTextureCache } from "../../webgl/gradient-texture";
 import type { Glyph } from "./glyph";
 import {
@@ -146,6 +147,32 @@ export class CartesianChart extends AbstractChart {
     _sizeName = "";
     _labelName = "";
     _colorIsString = false;
+
+    /**
+     * When the X (or Y) axis source column is post-aggregation
+     * `string`-typed, the build pipeline writes per-row dictionary slot
+     * indices into `_xData` (or `_yData`) instead of numeric values,
+     * and the render pass dispatches `renderCategoricalXTicks` /
+     * `renderCategoricalYTicks` instead of the numeric axis painter.
+     *
+     * The companion `_xCategoryDictionary` / `_xCategorySeen` pair is
+     * built lazily during `processCartesianChunk` in first-seen row
+     * order; `(null)` is appended on first encounter of an invalid row
+     * rather than reserved at slot 0, so charts without missing values
+     * don't get a phantom slot.
+     *
+     * `_xCategoryDomain` is materialized once per frame in
+     * `cartesian-render` and held for chrome overlay redraws (same
+     * lifecycle as `_lastXDomain` on the numeric path).
+     */
+    _xIsString = false;
+    _yIsString = false;
+    _xCategoryDictionary: string[] = [];
+    _yCategoryDictionary: string[] = [];
+    _xCategorySeen: Map<string, number> = new Map();
+    _yCategorySeen: Map<string, number> = new Map();
+    _xCategoryDomain: CategoricalDomain | null = null;
+    _yCategoryDomain: CategoricalDomain | null = null;
     _splitGroups: SplitGroup[] = [];
 
     //  Data extents
@@ -375,11 +402,23 @@ export class CartesianChart extends AbstractChart {
         // (the prior accumulator); the union is in `_xMin` etc., so we
         // copy it back. Idempotent across multi-chunk uploads — every
         // chunk leaves the accumulator equal to the running union.
+        //
+        // Categorical axes opt out: slot indices are first-seen-order
+        // and only meaningful within a single frame's dictionary, so
+        // expanding across frames would mix dictionaries and shift
+        // every category's slot. Force-fit those axes per frame
+        // instead.
         if (this._pluginConfig.domain_mode === "expand") {
-            this._expandedXMin = this._xMin;
-            this._expandedXMax = this._xMax;
-            this._expandedYMin = this._yMin;
-            this._expandedYMax = this._yMax;
+            if (!this._xIsString) {
+                this._expandedXMin = this._xMin;
+                this._expandedXMax = this._xMax;
+            }
+
+            if (!this._yIsString) {
+                this._expandedYMin = this._yMin;
+                this._expandedYMax = this._yMax;
+            }
+
             this._expandedColorMin = this._colorMin;
             this._expandedColorMax = this._colorMax;
             this._expandedSizeMin = this._sizeMin;