@perspective-dev/viewer-charts 4.3.0

package/src/ts/layout/facet-grid.ts

@@ -0,0 +1,346 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import { PlotLayout, type PlotRect } from "./plot-layout";
+
+/**
+ * Tri-state axis mode.
+ *
+ *   - `"outer"` — one shared axis band reserved at the grid edge;
+ *     `outerXAxisRect` / `outerYAxisRect` populated, per-cell gutter
+ *     collapsed to 0 on that side. Caller paints the shared axis
+ *     once per frame using the grid's outer rect.
+ *   - `"cell"` — every cell reserves its own gutter on that side;
+ *     caller paints one axis per cell. Outer rect is undefined.
+ *   - `"none"` — no gutter anywhere on that side: neither an outer
+ *     band nor a per-cell reservation. Intended for chart types with
+ *     no numeric axis at all (treemap, sunburst). When BOTH axes are
+ *     `"none"` cells are also made flush on the right so adjacent
+ *     plot rects share a boundary.
+ *
+ * Defaults to `"cell"` when undefined.
+ */
+export type AxisMode = "outer" | "cell" | "none";
+
+export interface FacetGridOptions {
+    cssWidth: number;
+    cssHeight: number;
+
+    /**
+     * See {@link AxisMode}. Default `"cell"`.
+     */
+    xAxis?: AxisMode;
+
+    /**
+     * See {@link AxisMode}. Default `"cell"`.
+     */
+    yAxis?: AxisMode;
+
+    /**
+     * Reserve a right gutter for a single shared legend.
+     */
+    hasLegend?: boolean;
+
+    /** Axis-label allowance (consumed only when the corresponding axis
+     *  mode produces a gutter — outer band or per-cell). */
+    hasXLabel?: boolean;
+    hasYLabel?: boolean;
+
+    /**
+     * Per-facet title strip height (px). 0 disables.
+     */
+    titleBand?: number;
+
+    /**
+     * Pixel gap between adjacent cells. Carved out of the grid
+     * interior before cell sizing; outer edges of the leftmost /
+     * rightmost columns and top / bottom rows are unaffected. Default
+     * 0 (flush cells).
+     */
+    gap?: number;
+}
+
+export interface FacetCell {
+    index: number;
+    label: string;
+
+    /**
+     * Sub-plot layout. Every cell in a grid has *identical*
+     * `plotRect.width` and `plotRect.height` — cell internal margins
+     * do not vary by edge position. Shared-axis gutters live in
+     * `FacetGrid.outerXAxisRect` / `outerYAxisRect` instead, painted
+     * once per frame by the caller.
+     */
+    layout: PlotLayout;
+
+    /**
+     * Title strip above the facet's plot rect, if `titleBand > 0`.
+     */
+    titleRect?: PlotRect;
+    isLeftEdge: boolean;
+    isBottomEdge: boolean;
+}
+
+export interface FacetGrid {
+    cells: FacetCell[];
+
+    /**
+     * Right-gutter rect for the shared legend.
+     */
+    legendRect?: PlotRect;
+
+    /**
+     * Outer band reserved for the shared X axis (ticks + label). Only
+     * set when `xAxis === "outer"`. Spans the grid interior's
+     * horizontal extent and sits immediately below the bottom row of
+     * cells.
+     */
+    outerXAxisRect?: PlotRect;
+
+    /**
+     * Outer band reserved for the shared Y axis (ticks + label). Only
+     * set when `yAxis === "outer"`. Spans the grid interior's
+     * vertical extent and sits immediately left of the leftmost
+     * column of cells.
+     */
+    outerYAxisRect?: PlotRect;
+}
+
+/**
+ * Collect the bottom-row cells' `PlotLayout`s — i.e. the cells that
+ * sit on the grid's bottom edge. Shared-X axis renderers paint X
+ * ticks aligned to each of these. Empty when the grid has zero cells.
+ */
+export function bottomRowLayouts(grid: FacetGrid): PlotLayout[] {
+    return grid.cells.filter((c) => c.isBottomEdge).map((c) => c.layout);
+}
+
+/**
+ * Collect the left-column cells' `PlotLayout`s — symmetric to
+ * {@link bottomRowLayouts} for the shared-Y axis path.
+ */
+export function leftColumnLayouts(grid: FacetGrid): PlotLayout[] {
+    return grid.cells.filter((c) => c.isLeftEdge).map((c) => c.layout);
+}
+
+// Per-cell internal gutter defaults mirror `PlotLayout`'s constants so
+// that a cell with `leftExtra: undefined` reserves the same space the
+// outer band would reserve when the axis is shared. Keep these in sync
+// with `plot-layout.ts`.
+const CELL_LEFT_GUTTER = 55;
+const CELL_BOTTOM_GUTTER = 24;
+const AXIS_LABEL_W = 16;
+const AXIS_LABEL_H = 18;
+
+const TITLE_BAND_DEFAULT = 18;
+const LEGEND_GUTTER = 96;
+
+/**
+ * Pick `(cols, rows)` so that each resulting cell's aspect ratio is as
+ * close to 1 as possible given the grid interior. Sweeps `cols ∈ [1,
+ * count]` with `rows = ceil(count / cols)` and minimizes
+ * `max(cellW/cellH, cellH/cellW)`. Ties break toward fewer total cells
+ * (less unused grid area).
+ */
+function pickGridShape(
+    count: number,
+    gridW: number,
+    gridH: number,
+    gap: number,
+): { cols: number; rows: number } {
+    if (count <= 1) {
+        return { cols: 1, rows: 1 };
+    }
+
+    let bestCols = 1;
+    let bestRows = count;
+    let bestCost = Infinity;
+    let bestTotal = count;
+    for (let cols = 1; cols <= count; cols++) {
+        const rows = Math.ceil(count / cols);
+        const cellW = Math.max(1, (gridW - (cols - 1) * gap) / cols);
+        const cellH = Math.max(1, (gridH - (rows - 1) * gap) / rows);
+        const aspect = cellW / cellH;
+        const cost = Math.max(aspect, 1 / aspect);
+        const total = cols * rows;
+        if (cost < bestCost || (cost === bestCost && total < bestTotal)) {
+            bestCols = cols;
+            bestRows = rows;
+            bestCost = cost;
+            bestTotal = total;
+        }
+    }
+
+    return { cols: bestCols, rows: bestRows };
+}
+
+/**
+ * Arrange `labels.length` sub-plots in a row-major grid sized to fit
+ * `(cssWidth, cssHeight)`.
+ *
+ * Grid shape is chosen to minimize cell aspect distance from square
+ * given the container's grid interior: `cols ∈ [1, count]`,
+ * `rows = ceil(count / cols)`, tie-broken toward fewer total cells.
+ *
+ * **Invariant:** every `cells[i].layout.plotRect` has the same
+ * `width` and `height`. Shared-axis gutters are carved out of the
+ * outer canvas BEFORE cell sizing, so a cell's edge position never
+ * affects its internal margins. This lets per-facet draws reuse the
+ * same projection scale and lets shared ticks line up with the
+ * interior cell boundaries exactly.
+ *
+ * Axis modes — see {@link AxisMode}:
+ *   - `"outer"` → outer band rect is populated; per-cell gutter is 0.
+ *   - `"cell"` → outer band is undefined; each cell owns its own gutter.
+ *   - `"none"` → no gutter anywhere on that side; used by axis-less
+ *     chart types.
+ *
+ * Because all cells are identical in size, callers can sample *any*
+ * cell's layout (e.g. `cells[0].layout`) for tick / scale
+ * computations.
+ */
+export function buildFacetGrid(
+    labels: string[],
+    opts: FacetGridOptions,
+): FacetGrid {
+    const count = labels.length;
+    const { cssWidth, cssHeight } = opts;
+
+    if (count <= 0 || cssWidth <= 0 || cssHeight <= 0) {
+        return { cells: [] };
+    }
+
+    const titleBand = opts.titleBand ?? TITLE_BAND_DEFAULT;
+    const legendW = opts.hasLegend ? LEGEND_GUTTER : 0;
+
+    const xMode: AxisMode = opts.xAxis ?? "cell";
+    const yMode: AxisMode = opts.yAxis ?? "cell";
+
+    // Axis-less chart types (trees) benefit from fully-flush cells —
+    // no per-cell breathing on the right either, so adjacent plot
+    // rects share a boundary instead of leaving a 16 px seam.
+    const cellsFlush = xMode === "none" && yMode === "none";
+
+    // Outer margins: shared-axis gutters + legend gutter live OUTSIDE
+    // the per-cell rects.
+    const outerLeft =
+        yMode === "outer"
+            ? CELL_LEFT_GUTTER + (opts.hasYLabel ? AXIS_LABEL_W : 0)
+            : 0;
+    const outerBottom =
+        xMode === "outer"
+            ? CELL_BOTTOM_GUTTER + (opts.hasXLabel ? AXIS_LABEL_H : 0)
+            : 0;
+    const outerTop = 0;
+    const outerRight = legendW;
+
+    const gridX = outerLeft;
+    const gridY = outerTop;
+    const gridW = Math.max(1, cssWidth - outerLeft - outerRight);
+    const gridH = Math.max(1, cssHeight - outerTop - outerBottom);
+
+    // Carve the total inter-cell gap out of the grid interior before
+    // sizing cells so every cell remains identical in size (the
+    // grid-uniform invariant). Gaps only sit BETWEEN neighbors — not
+    // against the outer edges.
+    const gap = Math.max(0, opts.gap ?? 0);
+    const { cols, rows } = pickGridShape(count, gridW, gridH, gap);
+    const totalGapX = Math.max(0, cols - 1) * gap;
+    const totalGapY = Math.max(0, rows - 1) * gap;
+    const cellW = Math.max(1, (gridW - totalGapX) / cols);
+    const cellH = Math.max(1, (gridH - totalGapY) / rows);
+
+    const cells: FacetCell[] = [];
+    for (let i = 0; i < count; i++) {
+        const row = Math.floor(i / cols);
+        const col = i - row * cols;
+        const isBottomEdge = row === rows - 1 || i + cols >= count;
+        const isLeftEdge = col === 0;
+
+        const cellX = gridX + col * (cellW + gap);
+        const cellY = gridY + row * (cellH + gap);
+
+        // Carve a title strip from the top of each cell. The remaining
+        // rect becomes the per-cell `PlotLayout`.
+        const plotTop = cellY + titleBand;
+        const plotLeft = cellX;
+        const plotWidth = cellW;
+        const plotHeight = Math.max(1, cellH - titleBand);
+
+        // Per-cell gutters:
+        //   - "cell" → keep `PlotLayout` default (undefined).
+        //   - "outer" / "none" → collapse to 0 (no internal gutter).
+        // Per-cell labels only paint when the axis is per-cell.
+        const layout = new PlotLayout(cssWidth, cssHeight, {
+            hasXLabel: xMode === "cell" && opts.hasXLabel === true,
+            hasYLabel: yMode === "cell" && opts.hasYLabel === true,
+            hasLegend: false,
+            leftExtra: yMode === "cell" ? undefined : 0,
+            bottomExtra: xMode === "cell" ? undefined : 0,
+            rightExtra: cellsFlush ? 0 : undefined,
+            originX: plotLeft,
+            originY: plotTop,
+            cellWidth: plotWidth,
+            cellHeight: plotHeight,
+        });
+
+        const titleRect: PlotRect | undefined =
+            titleBand > 0
+                ? {
+                      x: plotLeft,
+                      y: cellY,
+                      width: plotWidth,
+                      height: titleBand,
+                  }
+                : undefined;
+
+        cells.push({
+            index: i,
+            label: labels[i],
+            layout,
+            titleRect,
+            isLeftEdge,
+            isBottomEdge,
+        });
+    }
+
+    const legendRect: PlotRect | undefined = opts.hasLegend
+        ? {
+              x: gridX + gridW,
+              y: outerTop,
+              width: legendW,
+              height: gridH,
+          }
+        : undefined;
+
+    const outerXAxisRect: PlotRect | undefined =
+        xMode === "outer"
+            ? {
+                  x: gridX,
+                  y: gridY + gridH,
+                  width: gridW,
+                  height: outerBottom,
+              }
+            : undefined;
+
+    const outerYAxisRect: PlotRect | undefined =
+        yMode === "outer"
+            ? {
+                  x: 0,
+                  y: gridY,
+                  width: outerLeft,
+                  height: gridH,
+              }
+            : undefined;
+
+    return { cells, legendRect, outerXAxisRect, outerYAxisRect };
+}

package/src/ts/layout/plot-layout.ts

@@ -0,0 +1,277 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+export interface PlotMargins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+
+export interface PlotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export interface PlotLayoutOptions {
+    hasXLabel: boolean;
+    hasYLabel: boolean;
+    hasLegend: boolean;
+
+    /**
+     * Additional CSS-pixel height reserved at the bottom of the plot for a
+     * hierarchical / rotated categorical X axis. Overrides the default 24px
+     * tick band. The axis-label allowance from `hasXLabel` is preserved.
+     */
+    bottomExtra?: number;
+
+    /**
+     * Total CSS-pixel width reserved at the left of the plot for a
+     * hierarchical categorical Y axis. Overrides the default `55 +
+     * hasYLabel*16` left gutter. The axis-label allowance from `hasYLabel`
+     * is preserved.
+     */
+    leftExtra?: number;
+
+    /**
+     * Total CSS-pixel width reserved at the right of the plot. Overrides
+     * the default (`80` when `hasLegend`, else `16`). Faceted cells
+     * without axes (treemap / sunburst in grid mode) pass `0` to make
+     * adjacent cell plot rects flush; axis-bearing charts leave it
+     * unset to keep the default breathing-room margin.
+     */
+    rightExtra?: number;
+
+    /**
+     * Absolute canvas-coordinate offset for this layout's plot origin.
+     * When set, `cssWidth` / `cssHeight` describe the *outer* canvas, and
+     * `originX` / `originY` name the top-left corner of the cell this
+     * layout represents. The cell's own width/height come from
+     * `cellWidth` / `cellHeight`. `margins` are computed relative to the
+     * cell then shifted into canvas-absolute space so projection
+     * matrices, scissor, and `dataToPixel` all operate in full-canvas
+     * coordinates without branching per-facet.
+     *
+     * When any of these fields is unset, the layout is single-plot: the
+     * cell occupies the whole canvas and `originX` / `originY` default
+     * to 0.
+     */
+    originX?: number;
+    originY?: number;
+    cellWidth?: number;
+    cellHeight?: number;
+}
+
+/**
+ * Coordinates margins and coordinate transforms between WebGL and Canvas2D.
+ * All measurements are in CSS pixels (not physical/DPR-scaled pixels).
+ */
+export class PlotLayout {
+    readonly margins: PlotMargins;
+    readonly plotRect: PlotRect;
+    readonly cssWidth: number;
+    readonly cssHeight: number;
+
+    // Padded domain set by buildProjectionMatrix, used by dataToPixel
+    // and pixelToData for tooltip hit-testing.
+    paddedXMin = 0;
+    paddedXMax = 1;
+    paddedYMin = 0;
+    paddedYMax = 1;
+
+    constructor(
+        cssWidth: number,
+        cssHeight: number,
+        options: PlotLayoutOptions,
+    ) {
+        this.cssWidth = cssWidth;
+        this.cssHeight = cssHeight;
+
+        const baseLeft = options.leftExtra ?? 55;
+        const left = baseLeft + (options.hasYLabel ? 16 : 0);
+        const baseBottom = options.bottomExtra ?? 24;
+        const bottom = baseBottom + (options.hasXLabel ? 18 : 0);
+        const top = 0;
+        const right = options.rightExtra ?? (options.hasLegend ? 80 : 16);
+
+        // Facet cells: the sub-plot lives at `(originX, originY)` within a
+        // larger canvas of size `(cssWidth, cssHeight)`. Its own bounds are
+        // `cellWidth × cellHeight`. The gutters above are then interpreted
+        // inside that cell, and `margins` / `plotRect` are shifted into
+        // canvas-absolute coordinates. Single-plot layouts leave these
+        // unset, in which case `originX / originY = 0` and the cell
+        // occupies the whole canvas — identical to pre-facet semantics.
+        const originX = options.originX ?? 0;
+        const originY = options.originY ?? 0;
+        const cellW = options.cellWidth ?? cssWidth;
+        const cellH = options.cellHeight ?? cssHeight;
+
+        const marginLeftAbs = originX + left;
+        const marginTopAbs = originY + top;
+        const plotW = Math.max(1, cellW - left - right);
+        const plotH = Math.max(1, cellH - top - bottom);
+        const marginRightAbs = cssWidth - (marginLeftAbs + plotW);
+        const marginBottomAbs = cssHeight - (marginTopAbs + plotH);
+
+        this.margins = {
+            top: marginTopAbs,
+            right: marginRightAbs,
+            bottom: marginBottomAbs,
+            left: marginLeftAbs,
+        };
+
+        this.plotRect = {
+            x: marginLeftAbs,
+            y: marginTopAbs,
+            width: plotW,
+            height: plotH,
+        };
+    }
+
+    /**
+     * Build an orthographic projection matrix that maps data coordinates
+     * [xMin..xMax, yMin..yMax] to the plot area sub-region of clip space [-1, 1].
+     *
+     * The matrix bakes margin offsets into the transform so that gl.viewport
+     * remains full-canvas and no scissor/sub-viewport is needed.
+     *
+     * `clamp`, when set, names the axis that carries the *value* (as
+     * opposed to categorical / positional) data. Today it only affects
+     * `requireZero`; both axes always receive symmetric `padRatio` padding.
+     *
+     * `requireZero`, when true, guarantees that the unpadded value `0`
+     * falls inside the clamped axis's final domain. For all-positive
+     * data the axis minimum is pinned at `0` (the baseline sits on the
+     * axis line); for all-negative data the maximum is pinned at `0`;
+     * for data that already straddles zero, nothing changes. Pairs with
+     * `clamp`, and is a no-op when `clamp` is unset.
+     *
+     * `padRatio` controls the symmetric cosmetic pad on both axes
+     * (default 2%). Charts that want plot edges flush with the axes
+     * (e.g. heatmap, whose cell rects already span the exact domain)
+     * pass `0`.
+     */
+    buildProjectionMatrix(
+        xMin: number,
+        xMax: number,
+        yMin: number,
+        yMax: number,
+        clamp?: "x" | "y",
+        requireZero?: boolean,
+        padRatio: number = 0.02,
+        xOrigin: number = 0,
+        yOrigin: number = 0,
+    ): Float32Array {
+        // Symmetric cosmetic padding on both axes (default 2%).
+        let xRange = xMax - xMin;
+        let yRange = yMax - yMin;
+        if (xRange === 0) {
+            xRange = 1;
+        }
+
+        if (yRange === 0) {
+            yRange = 1;
+        }
+
+        const xPad = xRange * padRatio;
+        const yPad = yRange * padRatio;
+
+        // Evaluate the zero-snap condition against the *pre-pad*
+        // values so that an exact-zero boundary (e.g. bar pipelines
+        // that snap `valMin` to 0) still qualifies — otherwise the
+        // padding step would tip the boundary slightly negative and
+        // the snap branch below would miss. Inclusive comparison is
+        // deliberate.
+        const snapYMin = requireZero && clamp === "y" && yMin >= 0;
+        const snapYMax = requireZero && clamp === "y" && yMax <= 0;
+        const snapXMin = requireZero && clamp === "x" && xMin >= 0;
+        const snapXMax = requireZero && clamp === "x" && xMax <= 0;
+
+        xMin -= xPad;
+        xMax += xPad;
+        yMin -= yPad;
+        yMax += yPad;
+
+        // Pin the snapped boundary to exactly zero and give the
+        // opposite boundary a second pad for visual headroom above the
+        // tallest bar. No-op when data straddles zero (neither flag
+        // set) so no boundary collapses onto an in-range value.
+        if (snapYMin) {
+            yMin = 0;
+            yMax += yPad;
+        } else if (snapYMax) {
+            yMax = 0;
+            yMin -= yPad;
+        }
+
+        if (snapXMin) {
+            xMin = 0;
+            xMax += xPad;
+        } else if (snapXMax) {
+            xMax = 0;
+            xMin -= xPad;
+        }
+
+        // Store padded domain for dataToPixel
+        this.paddedXMin = xMin;
+        this.paddedXMax = xMax;
+        this.paddedYMin = yMin;
+        this.paddedYMax = yMax;
+
+        // Clip-space bounds for the plot area
+        const clipLeft = (2 * this.margins.left) / this.cssWidth - 1;
+        const clipRight = 1 - (2 * this.margins.right) / this.cssWidth;
+        const clipBottom = (2 * this.margins.bottom) / this.cssHeight - 1;
+        const clipTop = 1 - (2 * this.margins.top) / this.cssHeight;
+
+        // Scale and translate: rebased data [(min-origin), (max-origin)]
+        // → clip [clipMin, clipMax]. Callers that ship rebased values to
+        // the GPU pass the origin they used; for ordinary numeric data
+        // both origins default to 0 and the math collapses to the
+        // legacy `tx = clipLeft - sx*xMin` form. With a datetime axis
+        // the origin lifts ~1.7e12 out of `tx` before the f32
+        // narrowing in the matrix below, keeping shader cancellation
+        // precision-safe down to sub-millisecond granularity.
+        const sx = (clipRight - clipLeft) / (xMax - xMin);
+        const sy = (clipTop - clipBottom) / (yMax - yMin);
+        const tx = clipLeft - sx * (xMin - xOrigin);
+        const ty = clipBottom - sy * (yMin - yOrigin);
+
+        // Column-major 4x4 matrix
+        // prettier-ignore
+        return new Float32Array([
+            sx,  0,   0, 0,
+            0,   sy,  0, 0,
+            0,   0,  -1, 0,
+            tx,  ty,  0, 1,
+        ]);
+    }
+
+    /**
+     * Convert data coordinates to CSS pixel coordinates on the overlay canvas.
+     * Uses the padded domain from the last `buildProjectionMatrix` call so
+     * that pixel positions align exactly with the WebGL projection.
+     */
+    dataToPixel(dataX: number, dataY: number): { px: number; py: number } {
+        const { x, y, width, height } = this.plotRect;
+        const tx =
+            (dataX - this.paddedXMin) / (this.paddedXMax - this.paddedXMin);
+        const ty =
+            (dataY - this.paddedYMin) / (this.paddedYMax - this.paddedYMin);
+        return {
+            px: x + tx * width,
+            py: y + (1 - ty) * height, // Y is flipped (CSS Y goes down)
+        };
+    }
+}