@perspective-dev/viewer-charts 4.3.0

package/src/ts/charts/common/category-axis-resolver.ts

@@ -0,0 +1,314 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { ColumnDataMap, ColumnData } from "../../data/view-reader";
+import type { CategoricalLevel } from "../../axis/categorical-axis";
+import { buildGroupRuns } from "../../axis/categorical-axis-core";
+import { formatTickValue, formatDateTickValue } from "../../layout/ticks";
+
+export interface CategoryAxisResult {
+    /**
+     * Fully materialized hierarchical levels — labels and group runs are
+     * pre-resolved from the view's `__ROW_PATH_N__` dictionaries (or
+     * synthesized for non-string levels) so the chart can retain them
+     * past the `with_typed_arrays` callback scope. Empty when `groupBy`
+     * is empty.
+     */
+    rowPaths: CategoricalLevel[];
+
+    /**
+     * Rows that actually contribute a category (post-offset).
+     */
+    numCategories: number;
+
+    /**
+     * Leading rows skipped; callers use this to rebase per-row indices.
+     */
+    rowOffset: number;
+}
+
+export type AxisMode =
+    | { mode: "category" }
+    | {
+          mode: "numeric";
+          numericType: "date" | "datetime" | "integer" | "float";
+      };
+
+/**
+ * Numeric category-axis state. Shared across bar / candlestick / heatmap
+ * pipelines: when an axis is driven by exactly one non-string group_by /
+ * split_by level, glyphs anchor at real data values via `categoryPositions`
+ * and the chrome renders a numeric (date-aware) tick row.
+ */
+export interface NumericCategoryDomain {
+    min: number;
+    max: number;
+    isDate: boolean;
+    label: string;
+
+    /**
+     * Data-unit width of one category band, from min adjacent delta.
+     */
+    bandWidth: number;
+}
+
+/**
+ * Compute `categoryPositions` (per-row real data values) plus a
+ * `NumericCategoryDomain` summarizing min/max/bandWidth for a numeric
+ * row-path column. `bandWidth` falls back to the full domain when there
+ * are <2 distinct positions. Pivot rows for a single group_by come ASC
+ * by default, so a forward sweep for `minDelta` is sufficient.
+ *
+ * Returns `null` when the row-path column is missing or carries no
+ * `values` array (e.g. dictionary-encoded string column).
+ */
+export function resolveNumericCategoryDomain(
+    rpValues: ArrayLike<number> | null | undefined,
+    numCategories: number,
+    rowOffset: number,
+    label: string,
+    isDate: boolean,
+): {
+    categoryPositions: Float64Array;
+    numericCategoryDomain: NumericCategoryDomain;
+} | null {
+    if (!rpValues || numCategories <= 0) {
+        return null;
+    }
+
+    const categoryPositions = new Float64Array(numCategories);
+    let minVal = Infinity;
+    let maxVal = -Infinity;
+    for (let catI = 0; catI < numCategories; catI++) {
+        const v = rpValues[catI + rowOffset] as number;
+        categoryPositions[catI] = v;
+        if (v < minVal) {
+            minVal = v;
+        }
+
+        if (v > maxVal) {
+            maxVal = v;
+        }
+    }
+
+    let minDelta = Infinity;
+    for (let i = 1; i < numCategories; i++) {
+        const d = Math.abs(categoryPositions[i] - categoryPositions[i - 1]);
+        if (d > 0 && d < minDelta) {
+            minDelta = d;
+        }
+    }
+
+    if (!isFinite(minDelta) || minDelta === 0) {
+        minDelta = Math.max(1, maxVal - minVal);
+    }
+
+    return {
+        categoryPositions,
+        numericCategoryDomain: {
+            min: minVal - minDelta / 2,
+            max: maxVal + minDelta / 2,
+            isDate,
+            label,
+            bandWidth: minDelta,
+        },
+    };
+}
+
+/**
+ * Decide whether the categorical axis should render as a stringified
+ * category axis or a true numeric axis. Numeric mode is only used when
+ * there is exactly one `group_by` level AND that level is a non-string,
+ * non-boolean numeric type. Boolean and any multi-level case → category.
+ */
+export function resolveAxisMode(
+    groupBy: string[],
+    groupByTypes: Record<string, string>,
+): AxisMode {
+    if (groupBy.length !== 1) {
+        return { mode: "category" };
+    }
+
+    const t = groupByTypes[groupBy[0]];
+    if (t === "date" || t === "datetime" || t === "integer" || t === "float") {
+        return { mode: "numeric", numericType: t };
+    }
+
+    return { mode: "category" };
+}
+
+/**
+ * Stringify a single value from a non-string row-path column.
+ */
+function formatLevelValue(
+    value: number,
+    valid: boolean,
+    levelType: string,
+): string {
+    if (!valid) {
+        return "";
+    }
+
+    if (levelType === "boolean") {
+        return value ? "true" : "false";
+    }
+
+    if (levelType === "date" || levelType === "datetime") {
+        return formatDateTickValue(value);
+    }
+
+    if (levelType === "integer") {
+        return String(value | 0);
+    }
+
+    if (levelType === "float") {
+        return formatTickValue(value);
+    }
+
+    return String(value);
+}
+
+/**
+ * Synthesize a `(indices, dictionary)` pair from a non-string row-path
+ * column so the rest of the categorical axis machinery (label
+ * pre-resolution, run-length encoding) can run unchanged. The dictionary
+ * uses `""` at index 0 as the rollup-row sentinel — this preserves the
+ * existing skip-rollup loop's `s !== ""` check.
+ */
+export function synthesizeStringLevel(
+    rp: ColumnData,
+    numRows: number,
+    levelType: string,
+): { indices: Int32Array; dictionary: string[] } {
+    const values = rp.values!;
+    const valid = rp.valid;
+    const indices = new Int32Array(numRows);
+    const dictionary: string[] = [""];
+    const seen = new Map<string, number>();
+    seen.set("", 0);
+
+    for (let r = 0; r < numRows; r++) {
+        const isValid = valid ? !!((valid[r >> 3] >> (r & 7)) & 1) : true;
+        const v = values[r] as number;
+        const label = formatLevelValue(v, isValid, levelType);
+        let dictIdx = seen.get(label);
+        if (dictIdx === undefined) {
+            dictIdx = dictionary.length;
+            dictionary.push(label);
+            seen.set(label, dictIdx);
+        }
+
+        indices[r] = dictIdx;
+    }
+
+    return { indices, dictionary };
+}
+
+/**
+ * Resolve the category axis for a categorical-X chart (bar, candlestick,
+ * ohlc, …). Walks the `__ROW_PATH_N__` hierarchy columns, skips the
+ * rollup rows at the top ("Total" parent aggregates), and returns fully
+ * JS-owned level structures (precomputed labels + runs) plus the
+ * trimmed category count.
+ *
+ * Non-string row-path columns (date / datetime / integer / float /
+ * boolean group_by levels) are stringified into a synthetic dictionary
+ * so the downstream label / run-length machinery is type-agnostic.
+ *
+ * When `groupByLen === 0`, there are no row-path columns and the
+ * category axis falls back to the raw row index — callers infer that
+ * from `rowPaths.length === 0`.
+ */
+export function resolveCategoryAxis(
+    columns: ColumnDataMap,
+    numRows: number,
+    groupByLen: number,
+    levelTypes: string[] = [],
+): CategoryAxisResult {
+    type RawLevel = { indices: Int32Array; dictionary: string[] };
+    const rawRowPaths: RawLevel[] = [];
+    for (let n = 0; ; n++) {
+        const rp = columns.get(`__ROW_PATH_${n}__`);
+        if (!rp) {
+            break;
+        }
+
+        if (rp.type === "string" && rp.indices && rp.dictionary) {
+            rawRowPaths.push({
+                indices: rp.indices,
+                dictionary: rp.dictionary,
+            });
+        } else if (rp.values) {
+            const levelType = levelTypes[n] ?? "string";
+            rawRowPaths.push(synthesizeStringLevel(rp, numRows, levelType));
+        } else {
+            break;
+        }
+    }
+
+    let rowOffset = 0;
+    if (groupByLen > 0 && rawRowPaths.length > 0) {
+        while (rowOffset < numRows) {
+            let anyNonEmpty = false;
+            for (const rp of rawRowPaths) {
+                const s = rp.dictionary[rp.indices[rowOffset]];
+                if (s != null && s !== "") {
+                    anyNonEmpty = true;
+                    break;
+                }
+            }
+
+            if (anyNonEmpty) {
+                break;
+            }
+
+            rowOffset++;
+        }
+    }
+
+    const numCategories = Math.max(0, numRows - rowOffset);
+
+    const L = rawRowPaths.length;
+    const rowPaths: CategoricalLevel[] =
+        groupByLen > 0 && L > 0
+            ? rawRowPaths.map((rp, levelIdx) => {
+                  const labels = new Array<string>(numCategories);
+                  let maxLabelChars = 0;
+                  for (let r = 0; r < numCategories; r++) {
+                      const s = rp.dictionary[rp.indices[r + rowOffset]] ?? "";
+                      labels[r] = s;
+                      if (s.length > maxLabelChars) {
+                          maxLabelChars = s.length;
+                      }
+                  }
+
+                  // Only outer levels need the run-length encoding for
+                  // bracket rendering; leaves render per-row.
+                  const runs =
+                      levelIdx === L - 1
+                          ? []
+                          : buildGroupRuns(
+                                rp.indices,
+                                rp.dictionary,
+                                rowOffset,
+                                rowOffset + numCategories,
+                            ).map((run) => ({
+                                startIdx: run.startIdx - rowOffset,
+                                endIdx: run.endIdx - rowOffset,
+                                label: run.label,
+                            }));
+                  return { labels, runs, maxLabelChars };
+              })
+            : [];
+
+    return { rowPaths, numCategories, rowOffset };
+}

package/src/ts/charts/common/chrome-cache.ts

@@ -0,0 +1,79 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 "../canvas-types";
+
+export interface ChromeCacheChart {
+    _chromeCanvas: Canvas2D | null;
+    _chromeCache: ImageBitmap | null;
+    _chromeCacheDirty: boolean;
+    _chromeCacheGen: number;
+}
+
+/**
+ * Run the static-chrome cache pattern shared by sunburst + treemap.
+ * Resizes the canvas, paints the static layer (and snapshots it as an
+ * `ImageBitmap`) when dirty, otherwise blits the cache; then runs the
+ * caller-provided overlay layer for hover/highlight state.
+ *
+ * Returns the prepared `ctx` already in DPR-scaled space so the overlay
+ * callback can paint in CSS pixels — except `null` if either the canvas
+ * is missing a 2D context or the chart has nothing to paint.
+ */
+export function withChromeCache(
+    chart: ChromeCacheChart,
+    canvas: Canvas2D,
+    dpr: number,
+    cssWidth: number,
+    cssHeight: number,
+    drawStatic: (ctx: Context2D) => void,
+    drawOverlay: ((ctx: Context2D) => void) | null,
+): void {
+    const targetW = Math.round(cssWidth * dpr);
+    const targetH = Math.round(cssHeight * dpr);
+    if (canvas.width !== targetW || canvas.height !== targetH) {
+        canvas.width = targetW;
+        canvas.height = targetH;
+        chart._chromeCacheDirty = true;
+    }
+
+    const ctx = canvas.getContext("2d") as Context2D | null;
+    if (!ctx) {
+        return;
+    }
+
+    if (chart._chromeCacheDirty) {
+        chart._chromeCache?.close();
+        chart._chromeCache = null;
+        chart._chromeCacheDirty = false;
+        const gen = ++chart._chromeCacheGen;
+        drawStatic(ctx);
+        createImageBitmap(canvas).then((bmp) => {
+            if (chart._chromeCacheGen === gen) {
+                chart._chromeCache?.close();
+                chart._chromeCache = bmp;
+            } else {
+                bmp.close();
+            }
+        });
+    } else if (chart._chromeCache) {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        ctx.drawImage(chart._chromeCache, 0, 0);
+    }
+
+    if (drawOverlay) {
+        ctx.save();
+        ctx.scale(dpr, dpr);
+        drawOverlay(ctx);
+        ctx.restore();
+    }
+}

package/src/ts/charts/common/draw-tooltip-box.ts

@@ -0,0 +1,84 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 "../canvas-types";
+import type { Theme } from "../../theme/theme";
+
+/**
+ * Draw a freestanding tooltip box anchored near (cx, cy), measuring
+ * lines, sizing/clamping the box, painting bg/border, and laying out
+ * text rows. Shared by sunburst + treemap which need a non-PlotLayout
+ * anchor.
+ */
+export function drawTooltipBox(
+    ctx: Context2D,
+    theme: Theme,
+    lines: string[],
+    cx: number,
+    cy: number,
+    cssWidth: number,
+    cssHeight: number,
+    fontFamily: string,
+): void {
+    if (lines.length === 0) {
+        return;
+    }
+
+    const { tooltipBg, tooltipText, tooltipBorder } = theme;
+
+    ctx.font = `11px ${fontFamily}`;
+    const lineHeight = 16;
+    const padding = 8;
+    let maxWidth = 0;
+    for (const line of lines) {
+        const w = ctx.measureText(line).width;
+        if (w > maxWidth) {
+            maxWidth = w;
+        }
+    }
+
+    const boxW = maxWidth + padding * 2;
+    const boxH = lines.length * lineHeight + padding * 2 - 4;
+
+    let tx = cx + 12;
+    let ty = cy - boxH - 8;
+    if (tx + boxW > cssWidth) {
+        tx = cx - boxW - 12;
+    }
+
+    if (tx < 0) {
+        tx = 4;
+    }
+
+    if (ty < 0) {
+        ty = cy + 12;
+    }
+
+    if (ty + boxH > cssHeight) {
+        ty = cssHeight - boxH - 4;
+    }
+
+    ctx.fillStyle = tooltipBg;
+    ctx.strokeStyle = tooltipBorder;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.roundRect(tx, ty, boxW, boxH, 4);
+    ctx.fill();
+    ctx.stroke();
+
+    ctx.fillStyle = tooltipText;
+    ctx.textAlign = "left";
+    ctx.textBaseline = "top";
+    for (let i = 0; i < lines.length; i++) {
+        ctx.fillText(lines[i], tx + padding, ty + padding + i * lineHeight);
+    }
+}

package/src/ts/charts/common/leaf-color.ts

@@ -0,0 +1,92 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { TreeChartBase } from "./tree-chart";
+import type { Vec3 } from "../../theme/palette";
+import {
+    colorValueToT,
+    sampleGradient,
+    type GradientStop,
+} from "../../theme/gradient";
+
+/**
+ * Perceptual luminance for a 0..1 RGB triple. Used by tree-chart label
+ * painters to pick a contrasting text color over each leaf's fill.
+ */
+export function luminance(r: number, g: number, b: number): number {
+    return 0.299 * r + 0.587 * g + 0.114 * b;
+}
+
+/**
+ * Sample a gradient and drop the alpha channel. Treemap / sunburst
+ * fills carry alpha separately (see {@link leafRGBA}); this is the
+ * "just give me the RGB" entry point.
+ */
+export function sampleRGB(
+    stops: GradientStop[],
+    t: number,
+): [number, number, number] {
+    const c = sampleGradient(stops, t);
+    return [c[0], c[1], c[2]];
+}
+
+/**
+ * Resolve a leaf's fill color according to the chart's color mode:
+ *   - `"numeric"` — sign-aware gradient sample via `colorValueToT`.
+ *   - `"series"` / `"empty"` — discrete palette lookup keyed by the
+ *     node's `colorLabel` (composite of group_by levels in series mode;
+ *     `""` in empty mode, which maps to `palette[0]`).
+ *
+ * Returns RGB only; the alpha channel is applied separately by
+ * {@link leafRGBA} using `negativeAlpha` for leaves whose raw size was
+ * negative.
+ */
+export function leafColor(
+    chart: TreeChartBase,
+    nodeId: number,
+    stops: GradientStop[],
+    palette: Vec3[],
+): [number, number, number] {
+    const store = chart._nodeStore;
+    const colorValue = store.colorValue[nodeId];
+    if (
+        chart._colorMode === "numeric" &&
+        !isNaN(colorValue) &&
+        chart._colorMax > chart._colorMin
+    ) {
+        return sampleRGB(
+            stops,
+            colorValueToT(colorValue, chart._colorMin, chart._colorMax),
+        );
+    }
+
+    const idx = chart._uniqueColorLabels.get(store.colorLabel[nodeId]) ?? 0;
+    return palette[idx % palette.length] ?? [0, 0, 0];
+}
+
+/**
+ * `leafColor` + an alpha channel. Negative-size leaves receive
+ * `negativeAlpha` (mirrors `theme.areaOpacity` for area charts) so
+ * they stay visually distinguishable from positive leaves without
+ * disappearing.
+ */
+export function leafRGBA(
+    chart: TreeChartBase,
+    nodeId: number,
+    stops: GradientStop[],
+    palette: Vec3[],
+    negativeAlpha: number,
+): [number, number, number, number] {
+    const rgb = leafColor(chart, nodeId, stops, palette);
+    const alpha = chart._nodeStore.sizeSign[nodeId] < 0 ? negativeAlpha : 1.0;
+    return [rgb[0], rgb[1], rgb[2], alpha];
+}