@perspective-dev/viewer-charts 4.3.0

package/src/ts/axis/facet-chrome.ts

@@ -0,0 +1,42 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { Theme } from "../theme/theme";
+
+/**
+ * Paint a single facet's title strip — one line of centered text in the
+ * caller-supplied `rect`. Shared by every faceted chart family
+ * (cartesian, heatmap, …) so the title typography stays uniform.
+ */
+export function drawFacetTitle(
+    canvas: Canvas2D,
+    label: string,
+    rect: { x: number; y: number; width: number; height: number },
+    theme: Theme,
+    dpr: number,
+): void {
+    const ctx = canvas.getContext("2d") as Context2D | null;
+    if (!ctx) {
+        return;
+    }
+
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.scale(dpr, dpr);
+    ctx.font = `11px ${theme.fontFamily}`;
+    ctx.fillStyle = theme.labelColor;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(label, rect.x + rect.width / 2, rect.y + rect.height / 2);
+    ctx.restore();
+}

package/src/ts/axis/label-geometry.ts

@@ -0,0 +1,188 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/**
+ * Generic pixel-space label geometry helpers shared by the axis,
+ * legend, and tooltip overlays.
+ *
+ * All rectangles are in CSS pixels, origin top-left, Y-axis pointing down.
+ */
+
+import type { Context2D } from "../charts/canvas-types";
+
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export type Rotation = 0 | 45 | 90;
+
+/**
+ * Bounding rectangle of a text label anchored at `(cx, cy)`, accounting for
+ * rotation. Matches d3fc's approximation of rotated text bounds.
+ */
+export function labelRect(
+    cx: number,
+    cy: number,
+    textWidth: number,
+    textHeight: number,
+    rotation: Rotation,
+): Rect {
+    if (rotation === 0) {
+        return {
+            x: cx - textWidth / 2,
+            y: cy,
+            width: textWidth,
+            height: textHeight,
+        };
+    }
+
+    if (rotation === 90) {
+        return {
+            x: cx - textHeight / 2,
+            y: cy,
+            width: textHeight,
+            height: textWidth,
+        };
+    }
+
+    const w = (textWidth + textHeight) / Math.SQRT2;
+    return { x: cx - w, y: cy, width: w, height: w };
+}
+
+export function rectsOverlap(a: Rect, b: Rect): boolean {
+    return (
+        a.x <= b.x + b.width &&
+        b.x <= a.x + a.width &&
+        a.y <= b.y + b.height &&
+        b.y <= a.y + a.height
+    );
+}
+
+/**
+ * Rotated-label overlap heuristic from d3fc: for steeply-rotated labels
+ * the right edge of the previous box must precede the right edge of the
+ * next (plus a small gap).
+ */
+export function rotatedLabelsOverlap(a: Rect, b: Rect): boolean {
+    return a.x + a.width + 14 > b.x + b.width;
+}
+
+export function rectContained(inner: Rect, outer: Rect): boolean {
+    return (
+        inner.x >= outer.x &&
+        inner.x + inner.width <= outer.x + outer.width &&
+        inner.y >= outer.y &&
+        inner.y + inner.height <= outer.y + outer.height
+    );
+}
+
+/**
+ * Truncate `label` with a trailing ellipsis so the rendered width fits
+ * within `maxWidth`. Returns "" when even one character would overflow.
+ */
+export function truncateLabel(
+    ctx: Context2D,
+    label: string,
+    maxWidth: number,
+): string {
+    if (maxWidth <= 0) {
+        return "";
+    }
+
+    if (ctx.measureText(label).width <= maxWidth) {
+        return label;
+    }
+
+    let lo = 0;
+    let hi = label.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        const candidate = label.slice(0, mid) + "…";
+        if (ctx.measureText(candidate).width <= maxWidth) {
+            lo = mid;
+        } else {
+            hi = mid - 1;
+        }
+    }
+
+    return lo === 0 ? "" : label.slice(0, lo) + "…";
+}
+
+/**
+ * Word-wrap `text` into at most `maxLines` lines, each fitting within
+ * `maxWidth`. Breaks at the last whitespace before the fit boundary
+ * when possible, falls back to a hard character break otherwise. The
+ * final line is ellipsis-truncated via {@link truncateLabel} if it
+ * still doesn't fit. Returns `[]` when nothing meaningful fits (only
+ * one line of ≤ 2 chars after wrapping).
+ */
+export function wrapLabel(
+    ctx: Context2D,
+    text: string,
+    maxWidth: number,
+    maxLines: number,
+): string[] {
+    if (maxLines <= 0 || maxWidth <= 0) {
+        return [];
+    }
+
+    if (ctx.measureText(text).width <= maxWidth) {
+        return [text];
+    }
+
+    const lines: string[] = [];
+    let remaining = text;
+
+    while (remaining.length > 0 && lines.length < maxLines) {
+        const isLastLine = lines.length === maxLines - 1;
+
+        let fitLen = remaining.length;
+        while (
+            fitLen > 0 &&
+            ctx.measureText(remaining.slice(0, fitLen)).width > maxWidth
+        ) {
+            fitLen--;
+        }
+
+        if (fitLen === 0) {
+            fitLen = 1;
+        }
+
+        if (fitLen === remaining.length) {
+            lines.push(remaining);
+            break;
+        }
+
+        let breakAt = fitLen;
+        const spaceIdx = remaining.lastIndexOf(" ", fitLen);
+        if (spaceIdx > 0) {
+            breakAt = spaceIdx;
+        }
+
+        if (isLastLine) {
+            lines.push(truncateLabel(ctx, remaining, maxWidth));
+            break;
+        }
+
+        lines.push(remaining.slice(0, breakAt));
+        remaining = remaining.slice(breakAt).trimStart();
+    }
+
+    if (lines.length === 1 && lines[0].length <= 2) {
+        return [];
+    }
+
+    return lines;
+}

package/src/ts/axis/legend.ts

@@ -0,0 +1,218 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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, PlotRect } from "../layout/plot-layout";
+import { formatTickValue } from "../layout/ticks";
+import {
+    colorValueToT,
+    sampleGradient,
+    type GradientStop,
+} from "../theme/gradient";
+import type { Theme } from "../theme/theme";
+
+function rgbCss(c: [number, number, number, number]): string {
+    return `rgb(${Math.round(c[0] * 255)},${Math.round(c[1] * 255)},${Math.round(c[2] * 255)})`;
+}
+
+/**
+ * Render a vertical color gradient legend on the Canvas2D overlay.
+ * Only call when a color column is active. When `colorDomain` crosses
+ * zero the 50% stop (sign pivot) is annotated with a tick + `0` label.
+ *
+ * Per-facet wrapper; computes the anchor from `layout` and delegates
+ * to {@link renderLegendAt}. Facet grids render one shared gradient
+ * legend and pass an explicit rect to `renderLegendAt` directly.
+ */
+export function renderLegend(
+    canvas: Canvas2D,
+    layout: PlotLayout,
+    colorDomain: { min: number; max: number; label: string },
+    stops: GradientStop[],
+    theme: Theme,
+    formatter?: (v: number) => string,
+): void {
+    const rect: PlotRect = {
+        x: layout.plotRect.x + layout.plotRect.width + 12,
+        y: layout.margins.top + 20,
+        width: Math.max(
+            1,
+            layout.cssWidth - layout.plotRect.x - layout.plotRect.width - 12,
+        ),
+        height: Math.max(1, layout.plotRect.height),
+    };
+    renderLegendAt(canvas, rect, colorDomain, stops, theme, formatter);
+}
+
+/**
+ * Render a gradient legend at an explicit canvas-absolute rect.
+ * Used by facet grids that paint one legend for the whole grid and
+ * by single-plot charts through {@link renderLegend}.
+ */
+export function renderLegendAt(
+    canvas: Canvas2D,
+    rect: PlotRect,
+    colorDomain: { min: number; max: number; label: string },
+    stops: GradientStop[],
+    theme: Theme,
+    formatter: (v: number) => string = formatTickValue,
+): void {
+    const ctx = canvas.getContext("2d") as Context2D | null;
+    if (!ctx) {
+        return;
+    }
+
+    const textColor = theme.legendText;
+    const borderColor = theme.legendBorder;
+    const fontFamily = theme.fontFamily;
+
+    const barWidth = 16;
+    const barHeight = Math.min(120, rect.height * 0.4);
+    const x = rect.x;
+    const y = rect.y;
+
+    ctx.fillStyle = textColor;
+    ctx.font = `9px ${fontFamily}`;
+    ctx.textAlign = "left";
+    ctx.textBaseline = "bottom";
+    ctx.fillText(colorDomain.label, x, y - 4);
+
+    // Paint the gradient by walking `colorDomain.min..max` top→bottom and
+    // feeding each value through `colorValueToT` so the legend matches the
+    // sign-aware mapping used by the GPU / treemap paths.
+    const topVal = colorDomain.max;
+    const bottomVal = colorDomain.min;
+    const gradient = ctx.createLinearGradient(0, y, 0, y + barHeight);
+    const SAMPLES = 16;
+    for (let i = 0; i <= SAMPLES; i++) {
+        const offset = i / SAMPLES;
+        const v = topVal + offset * (bottomVal - topVal);
+        const t = colorValueToT(v, colorDomain.min, colorDomain.max);
+        const rgba = sampleGradient(stops, t);
+        gradient.addColorStop(offset, rgbCss(rgba));
+    }
+
+    ctx.fillStyle = gradient;
+    ctx.fillRect(x, y, barWidth, barHeight);
+
+    ctx.strokeStyle = borderColor;
+    ctx.lineWidth = 1;
+    ctx.strokeRect(x, y, barWidth, barHeight);
+
+    ctx.fillStyle = textColor;
+    ctx.font = `10px ${fontFamily}`;
+    ctx.textAlign = "left";
+    ctx.textBaseline = "middle";
+
+    const labelX = x + barWidth + 5;
+    ctx.fillText(formatter(colorDomain.max), labelX, y + 2);
+    ctx.fillText(
+        formatter((colorDomain.min + colorDomain.max) / 2),
+        labelX,
+        y + barHeight / 2,
+    );
+    ctx.fillText(formatter(colorDomain.min), labelX, y + barHeight - 2);
+
+    // Sign-pivot marker when the data crosses zero: a small tick on the
+    // right edge of the bar + a "0" label.
+    if (colorDomain.min < 0 && colorDomain.max > 0) {
+        const zeroOffset =
+            (colorDomain.max - 0) / (colorDomain.max - colorDomain.min);
+        const zeroY = y + zeroOffset * barHeight;
+        ctx.strokeStyle = textColor;
+        ctx.lineWidth = 1;
+        ctx.beginPath();
+        ctx.moveTo(x + barWidth, zeroY);
+        ctx.lineTo(x + barWidth + 4, zeroY);
+        ctx.stroke();
+        ctx.fillStyle = textColor;
+        ctx.fillText("0", labelX, zeroY);
+    }
+}
+
+/**
+ * Render a categorical legend with discrete colored swatches.
+ * Used when split_by or string color columns produce distinct categories.
+ *
+ * The per-facet wrapper; computes the anchor from `layout` and delegates
+ * to {@link renderCategoricalLegendAt}. Facet grids that render one
+ * shared legend pass an explicit rect to `renderCategoricalLegendAt`
+ * directly.
+ */
+export function renderCategoricalLegend(
+    canvas: Canvas2D,
+    layout: PlotLayout,
+    labels: Map<string, number>,
+    palette: [number, number, number][],
+    theme: Theme,
+): void {
+    const rect: PlotRect = {
+        x: layout.plotRect.x + layout.plotRect.width + 12,
+        y: layout.margins.top + 10,
+        width: Math.max(
+            1,
+            layout.cssWidth - layout.plotRect.x - layout.plotRect.width - 12,
+        ),
+        height: Math.max(1, layout.plotRect.height),
+    };
+    renderCategoricalLegendAt(canvas, rect, labels, palette, theme);
+}
+
+/**
+ * Render a categorical legend at an explicit canvas-absolute rect.
+ * Used by facet grids that paint one legend for the whole grid and by
+ * single-plot charts through {@link renderCategoricalLegend}.
+ */
+export function renderCategoricalLegendAt(
+    canvas: Canvas2D,
+    rect: PlotRect,
+    labels: Map<string, number>,
+    palette: [number, number, number][],
+    theme: Theme,
+): void {
+    const ctx = canvas.getContext("2d") as Context2D | null;
+    if (!ctx) {
+        return;
+    }
+
+    if (labels.size === 0) {
+        return;
+    }
+
+    const textColor = theme.legendText;
+    const fontFamily = theme.fontFamily;
+
+    const swatchSize = 10;
+    const lineHeight = 18;
+    const x = rect.x;
+    let y = rect.y + lineHeight / 2;
+
+    ctx.font = `11px ${fontFamily}`;
+    ctx.textAlign = "left";
+    ctx.textBaseline = "middle";
+
+    for (const [label, idx] of labels) {
+        if (y + swatchSize / 2 > rect.y + rect.height) {
+            break;
+        }
+
+        const color = palette[idx] ??
+            palette[idx % palette.length] ?? [0, 0, 0];
+        ctx.fillStyle = `rgb(${Math.round(color[0] * 255)},${Math.round(color[1] * 255)},${Math.round(color[2] * 255)})`;
+        ctx.fillRect(x, y - swatchSize / 2, swatchSize, swatchSize);
+
+        ctx.fillStyle = textColor;
+        ctx.fillText(label, x + swatchSize + 6, y);
+
+        y += lineHeight;
+    }
+}