@perspective-dev/viewer-charts 4.3.0

package/src/css/perspective-viewer-charts.css

@@ -0,0 +1,95 @@
+:host {
+    position: relative;
+    display: block;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    font-family: inherit;
+
+    /* font-family: var(--psp-interface-monospace--font-family, inherit); */
+    /* --psp-charts--font-family: var(font-family, inherit); */
+
+    --psp-charts--tooltip--color: var(--psp--color);
+    --psp-charts--tooltip--background: var(--psp--background-color);
+    --psp-charts--tooltip--border-color: var(--psp-inactive--border-color);
+}
+
+.webgl-container {
+    position: absolute;
+    top: 6px;
+    left: 6px;
+    right: 6px;
+    bottom: 6px;
+}
+
+.webgl-canvas {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    top: 0;
+    left: 0;
+}
+
+.webgl-gridlines {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    top: 0;
+    left: 0;
+    pointer-events: none;
+}
+
+.webgl-chrome {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    top: 0;
+    left: 0;
+    pointer-events: none;
+}
+
+.zoom-controls {
+    position: absolute;
+    top: 8px;
+    left: 50%;
+    transform: translateX(-50%);
+    display: none;
+    z-index: 2;
+    pointer-events: auto;
+}
+
+.zoom-controls.visible {
+    display: flex;
+    gap: 6px;
+}
+
+.zoom-reset {
+    background: var(--psp-charts--tooltip--background);
+    color: var(--psp-charts--tooltip--color);
+    border: 1px solid var(--psp-charts--tooltip--border-color);
+    border-radius: 4px;
+    padding: 4px 12px;
+    font: 11px var(--psp-charts--font-family);
+    cursor: pointer;
+    opacity: 0.7;
+    transition: opacity 0.15s;
+}
+
+.zoom-reset:hover {
+    opacity: 1;
+}
+
+.webgl-tooltip {
+    position: absolute;
+    pointer-events: auto;
+    font: 11px var(--psp-charts--font-family);
+    background: var(--psp-charts--tooltip--background);
+    color: var(--psp-charts--tooltip--color);
+    border: 1px solid var(--psp-charts--tooltip--border-color);
+    border-radius: 3px;
+    padding: 3px;
+    overflow-y: auto;
+    white-space: pre;
+    z-index: 10;
+    line-height: 16px;
+}

package/src/ts/axis/axis-primitives.ts

@@ -0,0 +1,125 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { Context2D } from "../charts/canvas-types";
+import type { PlotRect } from "../layout/plot-layout";
+
+export const TICK_SIZE = 5;
+
+/**
+ * One horizontal row of numeric axis ticks + labels at CSS-pixel `axisY`.
+ * `side` selects tick direction (down into the bottom margin or up into
+ * the top margin) and the corresponding label baseline. Caller owns
+ * `strokeStyle`, `fillStyle`, `font`, and `lineWidth`.
+ */
+export function drawXTickRow(
+    ctx: Context2D,
+    plot: PlotRect,
+    ticks: number[],
+    axisY: number,
+    side: "top" | "bottom",
+    xToPixel: (v: number) => number,
+    format: (v: number) => string,
+): void {
+    const dir = side === "bottom" ? 1 : -1;
+    ctx.textAlign = "center";
+    ctx.textBaseline = side === "bottom" ? "top" : "bottom";
+    const labelOffset = dir * (TICK_SIZE + 3);
+    for (const tick of ticks) {
+        const px = xToPixel(tick);
+        if (px < plot.x - 1 || px > plot.x + plot.width + 1) {
+            continue;
+        }
+
+        ctx.beginPath();
+        ctx.moveTo(px, axisY);
+        ctx.lineTo(px, axisY + dir * TICK_SIZE);
+        ctx.stroke();
+        ctx.fillText(format(tick), px, axisY + labelOffset);
+    }
+}
+
+/**
+ * One vertical column of numeric axis ticks + labels at CSS-pixel `axisX`.
+ * `side` selects tick direction (out toward the left or right margin) and
+ * the corresponding label alignment. Caller owns styling state.
+ */
+export function drawYTickColumn(
+    ctx: Context2D,
+    plot: PlotRect,
+    ticks: number[],
+    axisX: number,
+    side: "left" | "right",
+    yToPixel: (v: number) => number,
+    format: (v: number) => string,
+): void {
+    const dir = side === "left" ? -1 : 1;
+    ctx.textAlign = side === "left" ? "right" : "left";
+    ctx.textBaseline = "middle";
+    const labelOffset = dir * (TICK_SIZE + 3);
+    for (const tick of ticks) {
+        const py = yToPixel(tick);
+        if (py < plot.y - 1 || py > plot.y + plot.height + 1) {
+            continue;
+        }
+
+        ctx.beginPath();
+        ctx.moveTo(axisX, py);
+        ctx.lineTo(axisX + dir * TICK_SIZE, py);
+        ctx.stroke();
+        ctx.fillText(format(tick), axisX + labelOffset, py);
+    }
+}
+
+/**
+ * Vertical gridlines at numeric X ticks, clipped to `plot`.
+ */
+export function drawGridlinesX(
+    ctx: Context2D,
+    plot: PlotRect,
+    ticks: number[],
+    xToPixel: (v: number) => number,
+): void {
+    for (const tick of ticks) {
+        const px = Math.round(xToPixel(tick)) + 0.5;
+        if (px < plot.x || px > plot.x + plot.width) {
+            continue;
+        }
+
+        ctx.beginPath();
+        ctx.moveTo(px, plot.y);
+        ctx.lineTo(px, plot.y + plot.height);
+        ctx.stroke();
+    }
+}
+
+/**
+ * Horizontal gridlines at numeric Y ticks, clipped to `plot`.
+ */
+export function drawGridlinesY(
+    ctx: Context2D,
+    plot: PlotRect,
+    ticks: number[],
+    yToPixel: (v: number) => number,
+): void {
+    for (const tick of ticks) {
+        const py = Math.round(yToPixel(tick)) + 0.5;
+        if (py < plot.y || py > plot.y + plot.height) {
+            continue;
+        }
+
+        ctx.beginPath();
+        ctx.moveTo(plot.x, py);
+        ctx.lineTo(plot.x + plot.width, py);
+        ctx.stroke();
+    }
+}

package/src/ts/axis/bar-axis.ts

@@ -0,0 +1,345 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { Canvas2D, Context2D } from "../charts/canvas-types";
+import { PlotLayout } from "../layout/plot-layout";
+import { formatTickValue, formatDateTickValue } from "../layout/ticks";
+import { initCanvas } from "./canvas";
+import {
+    renderCategoricalXTicks,
+    renderCategoricalYTicks,
+    type CategoricalDomain,
+} from "./categorical-axis";
+import {
+    drawGridlinesX,
+    drawGridlinesY,
+    drawXTickRow,
+    drawYTickColumn,
+} from "./axis-primitives";
+import type { AxisDomain } from "./numeric-axis";
+import type { Theme } from "../theme/theme";
+
+function tickFormatter(
+    domain: AxisDomain,
+    ticks: number[],
+    override?: (v: number) => string,
+): (v: number) => string {
+    if (override) {
+        return override;
+    }
+
+    if (!domain.isDate) {
+        return formatTickValue;
+    }
+
+    const step = ticks.length > 1 ? ticks[1] - ticks[0] : 0;
+    return (v: number) => formatDateTickValue(v, step);
+}
+
+/**
+ * Render a numeric axis along the bottom or top of the plot area.
+ */
+function drawNumericXAxis(
+    ctx: Context2D,
+    layout: PlotLayout,
+    domain: AxisDomain,
+    ticks: number[],
+    side: "top" | "bottom",
+    theme: Theme,
+    formatter?: (v: number) => string,
+): void {
+    const { labelColor, fontFamily } = theme;
+    const { plotRect: plot } = layout;
+    const axisY = side === "bottom" ? plot.y + plot.height : plot.y;
+
+    ctx.fillStyle = labelColor;
+    ctx.font = `11px ${fontFamily}`;
+    ctx.lineWidth = 1;
+    drawXTickRow(
+        ctx,
+        plot,
+        ticks,
+        axisY,
+        side,
+        (v) => layout.dataToPixel(v, 0).px,
+        tickFormatter(domain, ticks, formatter),
+    );
+
+    ctx.font = `13px ${fontFamily}`;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "bottom";
+    ctx.fillText(
+        domain.label,
+        plot.x + plot.width / 2,
+        side === "bottom" ? layout.cssHeight - 2 : 10,
+    );
+}
+
+/**
+ * Render a numeric Y axis along either the left or right side of the plot
+ * area. The caller must have already `initCanvas`'d the target canvas.
+ * Used by bar charts with a categorical X and optional split Y axes.
+ */
+function drawYAxis(
+    ctx: Context2D,
+    layout: PlotLayout,
+    domain: AxisDomain,
+    ticks: number[],
+    side: "left" | "right",
+    theme: Theme,
+    formatter?: (v: number) => string,
+): void {
+    const { labelColor, fontFamily } = theme;
+    const { plotRect: plot } = layout;
+    const axisX = side === "left" ? plot.x : plot.x + plot.width;
+
+    ctx.fillStyle = labelColor;
+    ctx.font = `11px ${fontFamily}`;
+    ctx.lineWidth = 1;
+    drawYTickColumn(
+        ctx,
+        plot,
+        ticks,
+        axisX,
+        side,
+        (v) => layout.dataToPixel(0, v).py,
+        tickFormatter(domain, ticks, formatter),
+    );
+
+    ctx.font = `13px ${fontFamily}`;
+    ctx.save();
+    if (side === "left") {
+        ctx.translate(14, plot.y + plot.height / 2);
+        ctx.rotate(-Math.PI / 2);
+    } else {
+        ctx.translate(layout.cssWidth - 10, plot.y + plot.height / 2);
+        ctx.rotate(Math.PI / 2);
+    }
+
+    ctx.textAlign = "center";
+    ctx.textBaseline = "bottom";
+    ctx.fillText(domain.label, 0, 0);
+    ctx.restore();
+}
+
+/**
+ * The category-axis side of a bar chart can render as either a
+ * stringified hierarchical category axis or a true numeric axis (when
+ * the single group_by level is date / datetime / integer / float).
+ * Both shapes flow through `renderBarAxesChrome`; the discriminator is
+ * the `mode` field.
+ */
+export type BarCategoryAxis =
+    | { mode: "category"; domain: CategoricalDomain }
+    | { mode: "numeric"; domain: AxisDomain; ticks: number[] };
+
+/**
+ * Render a numeric date-aware axis along the bottom of the plot. Aliases
+ * the bar-axis bottom variant so heatmap can share the implementation.
+ */
+export function drawNumericCategoryX(
+    ctx: Context2D,
+    layout: PlotLayout,
+    domain: AxisDomain,
+    ticks: number[],
+    theme: Theme,
+    formatter?: (v: number) => string,
+): void {
+    drawNumericXAxis(ctx, layout, domain, ticks, "bottom", theme, formatter);
+}
+
+export function drawNumericCategoryY(
+    ctx: Context2D,
+    layout: PlotLayout,
+    domain: AxisDomain,
+    ticks: number[],
+    theme: Theme,
+    formatter?: (v: number) => string,
+): void {
+    drawYAxis(ctx, layout, domain, ticks, "left", theme, formatter);
+}
+
+/**
+ * Render bar-chart chrome: L-shaped axis lines, a categorical axis
+ * (bottom for Y Bar, left for X Bar), and one or two numeric axes on
+ * the opposite sides.
+ *
+ * `isHorizontal=true` flips orientation for X Bar: categorical axis on
+ * the left, numeric axes on the bottom (and top for dual-axis). The
+ * `altDomain`/`altTicks` arguments always describe the *secondary*
+ * numeric axis regardless of orientation.
+ */
+export interface BarAxesFormatters {
+    /** Formatter for the value (Y in vertical, X in horizontal) axis. */
+    value?: (v: number) => string;
+    /** Formatter for the secondary alt value axis. */
+    alt?: (v: number) => string;
+    /** Formatter for the numeric category axis (when `catAxis.mode === "numeric"`). */
+    category?: (v: number) => string;
+}
+
+export function renderBarAxesChrome(
+    canvas: Canvas2D,
+    catAxis: BarCategoryAxis,
+    valueDomain: AxisDomain,
+    valueTicks: number[],
+    layout: PlotLayout,
+    theme: Theme,
+    dpr: number,
+    altDomain?: AxisDomain,
+    altTicks?: number[],
+    isHorizontal = false,
+    formatters: BarAxesFormatters = {},
+): void {
+    const ctx = initCanvas(canvas, layout, dpr);
+    if (!ctx) {
+        return;
+    }
+
+    const { plotRect: plot } = layout;
+    ctx.strokeStyle = theme.axisLineColor;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.moveTo(plot.x, plot.y);
+    ctx.lineTo(plot.x, plot.y + plot.height);
+    ctx.lineTo(plot.x + plot.width, plot.y + plot.height);
+    if (altDomain) {
+        if (isHorizontal) {
+            ctx.moveTo(plot.x, plot.y);
+            ctx.lineTo(plot.x + plot.width, plot.y);
+        } else {
+            ctx.moveTo(plot.x + plot.width, plot.y);
+            ctx.lineTo(plot.x + plot.width, plot.y + plot.height);
+        }
+    }
+
+    ctx.stroke();
+
+    if (isHorizontal) {
+        if (catAxis.mode === "category") {
+            renderCategoricalYTicks(ctx, layout, catAxis.domain, theme);
+        } else {
+            drawNumericCategoryY(
+                ctx,
+                layout,
+                catAxis.domain,
+                catAxis.ticks,
+                theme,
+                formatters.category,
+            );
+        }
+
+        drawNumericXAxis(
+            ctx,
+            layout,
+            valueDomain,
+            valueTicks,
+            "bottom",
+            theme,
+            formatters.value,
+        );
+        if (altDomain && altTicks) {
+            const origMin = layout.paddedXMin;
+            const origMax = layout.paddedXMax;
+            layout.paddedXMin = altDomain.min;
+            layout.paddedXMax = altDomain.max;
+            drawNumericXAxis(
+                ctx,
+                layout,
+                altDomain,
+                altTicks,
+                "top",
+                theme,
+                formatters.alt,
+            );
+            layout.paddedXMin = origMin;
+            layout.paddedXMax = origMax;
+        }
+    } else {
+        if (catAxis.mode === "category") {
+            renderCategoricalXTicks(ctx, layout, catAxis.domain, theme);
+        } else {
+            drawNumericCategoryX(
+                ctx,
+                layout,
+                catAxis.domain,
+                catAxis.ticks,
+                theme,
+                formatters.category,
+            );
+        }
+
+        drawYAxis(
+            ctx,
+            layout,
+            valueDomain,
+            valueTicks,
+            "left",
+            theme,
+            formatters.value,
+        );
+        if (altDomain && altTicks) {
+            const origMin = layout.paddedYMin;
+            const origMax = layout.paddedYMax;
+            layout.paddedYMin = altDomain.min;
+            layout.paddedYMax = altDomain.max;
+            drawYAxis(
+                ctx,
+                layout,
+                altDomain,
+                altTicks,
+                "right",
+                theme,
+                formatters.alt,
+            );
+            layout.paddedYMin = origMin;
+            layout.paddedYMax = origMax;
+        }
+    }
+}
+
+/**
+ * Render gridlines at the numeric axis ticks. In vertical bar charts
+ * the gridlines run horizontally at numeric Y ticks; in horizontal bar
+ * charts they run vertically at numeric X ticks.
+ */
+export function renderBarGridlines(
+    canvas: Canvas2D,
+    layout: PlotLayout,
+    valueTicks: number[],
+    theme: Theme,
+    dpr: number,
+    isHorizontal = false,
+): void {
+    const ctx = initCanvas(canvas, layout, dpr);
+    if (!ctx) {
+        return;
+    }
+
+    ctx.strokeStyle = theme.gridlineColor;
+    ctx.lineWidth = 1;
+    if (isHorizontal) {
+        drawGridlinesX(
+            ctx,
+            layout.plotRect,
+            valueTicks,
+            (v) => layout.dataToPixel(v, 0).px,
+        );
+    } else {
+        drawGridlinesY(
+            ctx,
+            layout.plotRect,
+            valueTicks,
+            (v) => layout.dataToPixel(0, v).py,
+        );
+    }
+}

package/src/ts/axis/canvas.ts

@@ -0,0 +1,64 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { Canvas2D, Context2D } from "../charts/canvas-types";
+import type { PlotLayout } from "../layout/plot-layout";
+
+/**
+ * Destructive per-frame canvas setup: resize to CSS pixels × DPR,
+ * clear, and return a DPR-scaled 2D context. Call this exactly once
+ * per canvas per frame — setting `canvas.width` / `canvas.height`
+ * always wipes the bitmap and resets the transform, so calling it in
+ * a per-facet loop wipes every previously-drawn facet.
+ *
+ * Faceted renderers call this once per frame and then
+ * {@link getScaledContext} per facet to obtain the same context
+ * without re-wiping.
+ */
+export function initCanvas(
+    canvas: Canvas2D,
+    layout: PlotLayout,
+    dpr: number,
+): Context2D | null {
+    canvas.width = Math.round(layout.cssWidth * dpr);
+    canvas.height = Math.round(layout.cssHeight * dpr);
+    const ctx = canvas.getContext("2d") as Context2D;
+    if (!ctx) {
+        return null;
+    }
+
+    ctx.scale(dpr, dpr);
+    ctx.clearRect(0, 0, layout.cssWidth, layout.cssHeight);
+    return ctx;
+}
+
+/**
+ * Non-destructive variant: returns the 2D context with its transform
+ * forced to `scale(dpr, dpr)` via `setTransform` (idempotent — no
+ * stacking). Assumes `initCanvas` was already called on this canvas
+ * this frame; does NOT resize or clear.
+ *
+ * Intended for per-facet render helpers that must not wipe the shared
+ * canvas bitmap mid-frame.
+ */
+export function getScaledContext(
+    canvas: Canvas2D,
+    dpr: number,
+): Context2D | null {
+    const ctx = canvas.getContext("2d") as Context2D;
+    if (!ctx) {
+        return null;
+    }
+
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    return ctx;
+}