matterviz 0.3.6 → 0.4.0

package/dist/plot/scatter/adaptive-density.d.ts

@@ -0,0 +1,79 @@
+import { type Point2D, type Vec2 } from '../../math';
+import type { ScaleType } from '../core/types';
+export type NumericArray = ArrayLike<number>;
+export interface DensePointSeries<Metadata = Record<string, unknown>> {
+    id?: string | number;
+    label?: string;
+    x: NumericArray;
+    y: NumericArray;
+    metadata?: Metadata[] | Metadata;
+    point_ids?: ArrayLike<string | number>;
+    size_values?: ArrayLike<number | null>;
+    color?: string;
+}
+export interface DenseInternalPoint<Metadata = Record<string, unknown>> {
+    x: number;
+    y: number;
+    series_idx: number;
+    point_idx: number;
+    metadata?: Metadata;
+    point_id?: string | number;
+    size_value?: number | null;
+    cx: number;
+    cy: number;
+}
+export interface DensityBinResult {
+    counts: Uint32Array;
+    first_point_idxs: Int32Array;
+    first_series_idxs: Int32Array;
+    max_count: number;
+    visible_count: number;
+    x_bins: number;
+    y_bins: number;
+}
+export interface DensityBin {
+    x_bin: number;
+    y_bin: number;
+    count: number;
+    x_range: Vec2;
+    y_range: Vec2;
+}
+export interface PickNearestOptions {
+    x_range: Vec2;
+    y_range: Vec2;
+    x_scale: (value: number) => number;
+    y_scale: (value: number) => number;
+    radius_px?: number;
+}
+export interface PickIndex<Metadata = Record<string, unknown>> {
+    cells: Map<string, DenseInternalPoint<Metadata>[]>;
+    cell_size: number;
+    radius_px: number;
+}
+export interface PlotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface BinTransform {
+    forward: (value: number) => number;
+    inverse: (value: number) => number;
+}
+export type BinTransforms = {
+    x?: BinTransform;
+    y?: BinTransform;
+};
+export declare function scale_bin_transform(scale_type?: ScaleType): BinTransform;
+export declare const get_metadata_at: <Metadata>(metadata: DensePointSeries<Metadata>[`metadata`], point_idx: number) => Metadata | undefined;
+export declare const range_bounds: (range: Vec2) => Vec2;
+export declare function series_extents(series: readonly DensePointSeries[]): {
+    x: Vec2;
+    y: Vec2;
+};
+export declare function bin_points(series: readonly DensePointSeries[], x_range: Vec2, y_range: Vec2, x_bins: number, y_bins: number, transforms?: BinTransforms): DensityBinResult;
+export declare function density_bin_at_point(density: DensityBinResult, pointer: Point2D, plot_rect: PlotRect, x_range: Vec2, y_range: Vec2, transforms?: BinTransforms): DensityBin | null;
+export declare const should_render_points: (visible_count: number, plot_area_px: number, max_points: number, max_points_per_px: number) => boolean;
+export declare function build_pick_index<Metadata>(series: readonly DensePointSeries<Metadata>[], options: PickNearestOptions): PickIndex<Metadata>;
+export declare function pick_from_index<Metadata>(index: PickIndex<Metadata>, pointer: Point2D): DenseInternalPoint<Metadata> | null;
+export declare function first_point_in_bin<Metadata>(series: readonly DensePointSeries<Metadata>[], density: DensityBinResult, bin: Pick<DensityBin, `x_bin` | `y_bin`>, x_scale: (value: number) => number, y_scale: (value: number) => number): DenseInternalPoint<Metadata> | null;

package/dist/plot/scatter/adaptive-density.js

@@ -0,0 +1,217 @@
+import { LOG_EPS } from '../../math';
+import { get_arcsinh_threshold, get_scale_type_name } from '../core/types';
+const identity = { forward: (val) => val, inverse: (val) => val };
+// Map an axis scale_type to the transform density binning should happen in
+export function scale_bin_transform(scale_type) {
+    const type_name = get_scale_type_name(scale_type);
+    if (type_name === `log`) {
+        // Clamp to LOG_EPS (same floor as the rendered log scale) so bin edges align with the
+        // axis; non-positive samples are already dropped by the range filter in bin_points
+        return { forward: (val) => Math.log(Math.max(val, LOG_EPS)), inverse: Math.exp };
+    }
+    if (type_name !== `arcsinh`)
+        return identity;
+    const threshold = get_arcsinh_threshold(scale_type);
+    return {
+        forward: (val) => Math.asinh(val / threshold),
+        inverse: (val) => Math.sinh(val) * threshold,
+    };
+}
+// Data range of one bin: edges are uniform in transformed space, mapped back via inverse
+const bin_range = (txf, range, bin, n_bins) => {
+    const transform = txf ?? identity;
+    const [t_min, t_max] = range_bounds(range).map(transform.forward);
+    const step = (t_max - t_min || 1) / n_bins;
+    return [
+        transform.inverse(t_min + bin * step),
+        transform.inverse(t_min + (bin + 1) * step),
+    ];
+};
+export const get_metadata_at = (metadata, point_idx) => (Array.isArray(metadata) ? metadata[point_idx] : metadata);
+const cell_key = (x_bin, y_bin) => `${x_bin},${y_bin}`;
+export const range_bounds = (range) => range[0] <= range[1] ? range : [range[1], range[0]];
+const in_bounds = (value, min, max) => Number.isFinite(value) && value >= min && value <= max;
+const value_bin = (value, min, span, bins) => Math.min(bins - 1, Math.max(0, Math.floor(((value - min) / span) * bins)));
+const series_length = (srs) => Math.min(srs.x.length, srs.y.length);
+const padded_extent = (min, max) => {
+    if (!Number.isFinite(min) || !Number.isFinite(max))
+        return [0, 1];
+    if (min === max)
+        return [min - 0.5, max + 0.5];
+    const padding = (max - min) * 0.05;
+    return [min - padding, max + padding];
+};
+export function series_extents(series) {
+    let x_min = Infinity;
+    let x_max = -Infinity;
+    let y_min = Infinity;
+    let y_max = -Infinity;
+    for (const srs of series) {
+        const n_points = series_length(srs);
+        for (let idx = 0; idx < n_points; idx++) {
+            const x = srs.x[idx];
+            const y = srs.y[idx];
+            if (Number.isFinite(x)) {
+                if (x < x_min)
+                    x_min = x;
+                if (x > x_max)
+                    x_max = x;
+            }
+            if (Number.isFinite(y)) {
+                if (y < y_min)
+                    y_min = y;
+                if (y > y_max)
+                    y_max = y;
+            }
+        }
+    }
+    return { x: padded_extent(x_min, x_max), y: padded_extent(y_min, y_max) };
+}
+export function bin_points(series, x_range, y_range, x_bins, y_bins, transforms) {
+    const counts = new Uint32Array(x_bins * y_bins);
+    const first_point_idxs = new Int32Array(counts.length);
+    const first_series_idxs = new Int32Array(counts.length);
+    const [x_min, x_max] = range_bounds(x_range);
+    const [y_min, y_max] = range_bounds(y_range);
+    // Bin in transformed (scale) space so bins align with the axis pixel grid
+    const x_fwd = transforms?.x?.forward ?? identity.forward;
+    const y_fwd = transforms?.y?.forward ?? identity.forward;
+    const t_x_min = x_fwd(x_min);
+    const t_y_min = y_fwd(y_min);
+    const x_bin_scale = x_bins / (x_fwd(x_max) - t_x_min || 1);
+    const y_bin_scale = y_bins / (y_fwd(y_max) - t_y_min || 1);
+    const last_x_bin = x_bins - 1;
+    const last_y_bin = y_bins - 1;
+    let visible_count = 0;
+    let max_count = 0;
+    for (let series_idx = 0; series_idx < series.length; series_idx++) {
+        const srs = series[series_idx];
+        const n_points = series_length(srs);
+        for (let point_idx = 0; point_idx < n_points; point_idx++) {
+            const x = srs.x[point_idx];
+            const y = srs.y[point_idx];
+            if (!Number.isFinite(x) ||
+                !Number.isFinite(y) ||
+                x < x_min ||
+                x > x_max ||
+                y < y_min ||
+                y > y_max)
+                continue;
+            const raw_x_bin = Math.floor((x_fwd(x) - t_x_min) * x_bin_scale);
+            const raw_y_bin = Math.floor((y_fwd(y) - t_y_min) * y_bin_scale);
+            const x_bin = raw_x_bin < 0 ? 0 : raw_x_bin > last_x_bin ? last_x_bin : raw_x_bin;
+            const y_bin = raw_y_bin < 0 ? 0 : raw_y_bin > last_y_bin ? last_y_bin : raw_y_bin;
+            const idx = y_bin * x_bins + x_bin;
+            const count = ++counts[idx];
+            if (count === 1) {
+                first_series_idxs[idx] = series_idx;
+                first_point_idxs[idx] = point_idx;
+            }
+            visible_count++;
+            if (count > max_count)
+                max_count = count;
+        }
+    }
+    return {
+        counts,
+        first_point_idxs,
+        first_series_idxs,
+        max_count,
+        visible_count,
+        x_bins,
+        y_bins,
+    };
+}
+export function density_bin_at_point(density, pointer, plot_rect, x_range, y_range, transforms) {
+    const rel_x = pointer.x - plot_rect.x;
+    const rel_y = pointer.y - plot_rect.y;
+    if (rel_x < 0 || rel_y < 0 || rel_x >= plot_rect.width || rel_y >= plot_rect.height) {
+        return null;
+    }
+    const x_bin = value_bin(rel_x, 0, plot_rect.width || 1, density.x_bins);
+    // Screen coordinates grow downward, while density bins use bottom-up data Y.
+    const y_bin = density.y_bins - 1 - value_bin(rel_y, 0, plot_rect.height || 1, density.y_bins);
+    const count = density.counts[y_bin * density.x_bins + x_bin];
+    if (!count)
+        return null;
+    return {
+        x_bin,
+        y_bin,
+        count,
+        x_range: bin_range(transforms?.x, x_range, x_bin, density.x_bins),
+        y_range: bin_range(transforms?.y, y_range, y_bin, density.y_bins),
+    };
+}
+export const should_render_points = (visible_count, plot_area_px, max_points, max_points_per_px) => visible_count <= max_points ||
+    (plot_area_px > 0 && visible_count / plot_area_px <= max_points_per_px);
+const internal_point = (srs, series_idx, point_idx, x_scale, y_scale) => {
+    const x = srs.x[point_idx];
+    const y = srs.y[point_idx];
+    return {
+        x,
+        y,
+        cx: x_scale(x),
+        cy: y_scale(y),
+        series_idx,
+        point_idx,
+        metadata: get_metadata_at(srs.metadata, point_idx),
+        point_id: srs.point_ids?.[point_idx],
+        size_value: srs.size_values?.[point_idx],
+    };
+};
+export function build_pick_index(series, options) {
+    const { x_range, y_range, x_scale, y_scale, radius_px = 12 } = options;
+    const [x_min, x_max] = range_bounds(x_range);
+    const [y_min, y_max] = range_bounds(y_range);
+    const cell_size = Math.max(1, radius_px);
+    const cells = new Map();
+    for (let series_idx = 0; series_idx < series.length; series_idx++) {
+        const srs = series[series_idx];
+        const n_points = series_length(srs);
+        for (let point_idx = 0; point_idx < n_points; point_idx++) {
+            const x = srs.x[point_idx];
+            const y = srs.y[point_idx];
+            if (!in_bounds(x, x_min, x_max) || !in_bounds(y, y_min, y_max))
+                continue;
+            const point = internal_point(srs, series_idx, point_idx, x_scale, y_scale);
+            const key = cell_key(Math.floor(point.cx / cell_size), Math.floor(point.cy / cell_size));
+            const points = cells.get(key);
+            if (points)
+                points.push(point);
+            else
+                cells.set(key, [point]);
+        }
+    }
+    return { cells, cell_size, radius_px };
+}
+export function pick_from_index(index, pointer) {
+    const radius_sq = index.radius_px ** 2;
+    const center_x = Math.floor(pointer.x / index.cell_size);
+    const center_y = Math.floor(pointer.y / index.cell_size);
+    const cell_radius = Math.ceil(index.radius_px / index.cell_size);
+    let best = null;
+    let best_dist_sq = radius_sq;
+    for (let y_bin = center_y - cell_radius; y_bin <= center_y + cell_radius; y_bin++) {
+        for (let x_bin = center_x - cell_radius; x_bin <= center_x + cell_radius; x_bin++) {
+            for (const point of index.cells.get(cell_key(x_bin, y_bin)) ?? []) {
+                const dx = pointer.x - point.cx;
+                const dy = pointer.y - point.cy;
+                const dist_sq = dx * dx + dy * dy;
+                if (dist_sq > best_dist_sq)
+                    continue;
+                best_dist_sq = dist_sq;
+                best = point;
+            }
+        }
+    }
+    return best;
+}
+export function first_point_in_bin(series, density, bin, x_scale, y_scale) {
+    const idx = bin.y_bin * density.x_bins + bin.x_bin;
+    if (!density.counts[idx])
+        return null;
+    const series_idx = density.first_series_idxs[idx];
+    const point_idx = density.first_point_idxs[idx];
+    const srs = series[series_idx];
+    return srs ? internal_point(srs, series_idx, point_idx, x_scale, y_scale) : null;
+}

package/dist/plot/scatter/binned-scatter-types.d.ts

@@ -0,0 +1,59 @@
+import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
+import type { DenseInternalPoint } from './adaptive-density';
+import type ColorBar from '../core/components/ColorBar.svelte';
+import type { LabelPlacementConfig, ScaleType, ScatterHandlerProps } from '../core/types';
+import type { ComponentProps, Snippet } from 'svelte';
+export type BinnedColorScaleConfig = {
+    type?: ScaleType;
+    scheme?: D3ColorSchemeName | D3InterpolateName;
+    value_range?: [number, number];
+} | D3InterpolateName;
+export type BinnedSizeScaleConfig = {
+    type?: ScaleType;
+    radius_range?: [number, number];
+    value_range?: [number, number];
+    pick_radius?: number | `auto`;
+};
+export type BinnedDensityConfig = {
+    bin_px?: number;
+    color_scale?: BinnedColorScaleConfig;
+    color_bar?: ComponentProps<typeof ColorBar> | null;
+    auto_point_mode?: false | {
+        max_points?: number;
+        max_points_per_px?: number;
+    };
+    bin_click?: `zoom` | `point` | `none`;
+};
+export type BinnedRefLine = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    color?: string;
+    dash?: string;
+    width?: number;
+};
+export type BinnedOverlaysConfig = {
+    ref_lines?: BinnedRefLine[];
+};
+export type BinnedPointBasePayload<Metadata extends Record<string, unknown> = Record<string, unknown>> = ScatterHandlerProps<Metadata> & {
+    point: DenseInternalPoint<Metadata>;
+    color?: string;
+};
+export type BinnedPointDataFn<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = (payload: BinnedPointBasePayload<Metadata>) => PointData | null | undefined;
+export type BinnedPointPayload<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = BinnedPointBasePayload<Metadata> & {
+    point_data?: PointData;
+};
+export type BinnedPointTooltipPayload<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = BinnedPointPayload<Metadata, PointData>;
+export type BinnedPointLabelPlacementConfig = Partial<LabelPlacementConfig>;
+export type BinnedPointLabelsConfig<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = {
+    render?: Snippet<[BinnedPointPayload<Metadata, PointData>]>;
+    measure_text?: (payload: BinnedPointPayload<Metadata, PointData>) => string;
+    font_size?: string;
+    max_count?: number;
+    gap_px?: number;
+    placement?: BinnedPointLabelPlacementConfig;
+    leaders?: {
+        min_length_px?: number;
+    };
+};

package/dist/plot/scatter/binned-scatter-types.js

@@ -0,0 +1 @@
+export {};

package/dist/plot/scatter/index.d.ts

@@ -0,0 +1,7 @@
+export type { DensePointSeries } from './adaptive-density';
+export { default as BinnedScatterPlot } from './BinnedScatterPlot.svelte';
+export type { BinnedColorScaleConfig, BinnedDensityConfig, BinnedOverlaysConfig, BinnedPointBasePayload, BinnedPointDataFn, BinnedPointLabelPlacementConfig, BinnedPointLabelsConfig, BinnedPointPayload, BinnedPointTooltipPayload, BinnedRefLine, BinnedSizeScaleConfig, } from './binned-scatter-types';
+export { default as ElementScatter } from './ElementScatter.svelte';
+export { default as ScatterPlot } from './ScatterPlot.svelte';
+export { default as ScatterPlotControls } from './ScatterPlotControls.svelte';
+export { default as ScatterPoint } from './ScatterPoint.svelte';

package/dist/plot/scatter/index.js

@@ -0,0 +1,5 @@
+export { default as BinnedScatterPlot } from './BinnedScatterPlot.svelte';
+export { default as ElementScatter } from './ElementScatter.svelte';
+export { default as ScatterPlot } from './ScatterPlot.svelte';
+export { default as ScatterPlotControls } from './ScatterPlotControls.svelte';
+export { default as ScatterPoint } from './ScatterPoint.svelte';

package/dist/plot/scatter/scatter-data.d.ts

@@ -0,0 +1,19 @@
+import type { DataSeries, FillRegion, InternalPoint, LegendItem, PointStyle } from '..';
+import { type AxisRanges } from '../core/types';
+export type { AxisRanges };
+export declare function filter_series_to_ranges<Metadata = Record<string, unknown>>(series: readonly DataSeries<Metadata>[], ranges: AxisRanges): (DataSeries<Metadata> & {
+    filtered_data: InternalPoint<Metadata>[];
+})[];
+export type LegendFill = FillRegion & {
+    idx: number;
+    source_type: `fill_region` | `error_band`;
+    source_idx: number;
+};
+export type ScatterLegendItem = LegendItem & {
+    has_explicit_label?: boolean;
+};
+export declare function build_legend_data<Metadata = Record<string, unknown>>(series: readonly DataSeries<Metadata>[], computed_fills: readonly LegendFill[], color_scale_fn: (value: number) => string): ScatterLegendItem[];
+export declare function pick_tooltip_bg<Metadata = Record<string, unknown>>(point: {
+    color_value?: number | null;
+    point_style?: PointStyle;
+}, series: DataSeries<Metadata> | undefined, color_scale_fn: (value: number) => string): string;

package/dist/plot/scatter/scatter-data.js

@@ -0,0 +1,212 @@
+import { symbol_names } from '../../labels';
+import { get_series_color, get_series_symbol, process_prop, } from '../core/data-transform';
+import { is_fill_gradient } from '../core/fill-utils';
+import { DEFAULT_MARKERS } from '../core/types';
+const in_range = (val, lo, hi) => val != null && !isNaN(val) && val >= Math.min(lo, hi) && val <= Math.max(lo, hi);
+// Filter series data to only include points within bounds and augment with internal data.
+// Full x/y arrays are kept on each returned series (via spread) so connecting lines can
+// continue through off-range points; only filtered_data (rendered markers) is range-limited.
+export function filter_series_to_ranges(series, ranges) {
+    const [x_min, x_max] = ranges.x;
+    const [x2_min, x2_max] = ranges.x2;
+    const [y_min, y_max] = ranges.y;
+    const [y2_min, y2_max] = ranges.y2;
+    return (series
+        .map((data_series, series_idx) => {
+        if (!data_series) {
+            return {
+                x: [],
+                y: [],
+                visible: true,
+                filtered_data: [],
+                _id: series_idx,
+                orig_series_idx: series_idx,
+            };
+        }
+        if (!(data_series.visible ?? true)) {
+            return {
+                ...data_series,
+                visible: false,
+                filtered_data: [],
+                orig_series_idx: series_idx,
+            };
+        }
+        const { x: xs, y: ys, color_values, size_values, ...series_rest } = data_series;
+        const processed_points = xs.map((x_val, point_idx) => ({
+            x: x_val,
+            y: ys[point_idx],
+            color_value: color_values?.[point_idx],
+            metadata: process_prop(series_rest.metadata, point_idx),
+            point_style: process_prop(series_rest.point_style, point_idx),
+            point_hover: process_prop(series_rest.point_hover, point_idx),
+            point_label: process_prop(series_rest.point_label, point_idx),
+            point_offset: process_prop(series_rest.point_offset, point_idx),
+            series_idx,
+            point_idx,
+            size_value: size_values?.[point_idx],
+        }));
+        // Filter to plot bounds using the series' assigned axes (in_range handles
+        // inverted ranges like [3.5, 1.4])
+        const [series_x_min, series_x_max] = (data_series.x_axis ?? `x1`) === `x2` ? [x2_min, x2_max] : [x_min, x_max];
+        const [series_y_min, series_y_max] = (data_series.y_axis ?? `y1`) === `y2` ? [y2_min, y2_max] : [y_min, y_max];
+        const filtered_data = processed_points.filter(({ x, y }) => in_range(x, series_x_min, series_x_max) && in_range(y, series_y_min, series_y_max));
+        // orig_series_idx keeps auto-cycled colors/symbols stable across filtering
+        return { ...data_series, visible: true, filtered_data, orig_series_idx: series_idx };
+    })
+        // Drop series left completely empty after point filtering
+        .filter((srs) => (srs.filtered_data?.length ?? 0) > 0));
+}
+// Prepare legend items from series + computed fill regions, deduplicated by
+// legend_group::label (first occurrence wins across both series and fills)
+export function build_legend_data(series, computed_fills, color_scale_fn) {
+    const items = series.map((data_series, series_idx) => {
+        // Prefer top-level label, fall back to metadata label, then a generated default
+        const explicit_label = data_series?.label ??
+            (typeof data_series?.metadata === `object` &&
+                data_series.metadata !== null &&
+                `label` in data_series.metadata &&
+                typeof data_series.metadata.label === `string`
+                ? data_series.metadata.label
+                : null);
+        // Series-index defaults give auto-cycled colors/symbols
+        const series_default_color = get_series_color(series_idx);
+        const display_style = {
+            symbol_type: get_series_symbol(series_idx),
+            symbol_color: series_default_color,
+            line_color: series_default_color,
+        };
+        const series_markers = data_series?.markers ?? DEFAULT_MARKERS;
+        const first_point_style = Array.isArray(data_series?.point_style)
+            ? data_series.point_style[0]
+            : data_series?.point_style;
+        if (series_markers?.includes(`points`)) {
+            if (first_point_style) {
+                if (typeof first_point_style.symbol_type === `string` &&
+                    symbol_names.includes(first_point_style.symbol_type)) {
+                    display_style.symbol_type = first_point_style.symbol_type;
+                }
+                if (first_point_style.fill)
+                    display_style.symbol_color = first_point_style.fill;
+                // Fall back to stroke when the fill is missing/none/transparent
+                if (first_point_style.stroke &&
+                    (!display_style.symbol_color ||
+                        display_style.symbol_color === `none` ||
+                        display_style.symbol_color.startsWith(`rgba(`, 0))) {
+                    display_style.symbol_color = first_point_style.stroke;
+                }
+            }
+        }
+        else {
+            // No points marker: no symbol swatch in the legend
+            display_style.symbol_type = undefined;
+            display_style.symbol_color = undefined;
+        }
+        if (series_markers?.includes(`line`)) {
+            // Explicit line stroke, then color scale, then point colors, then series default
+            let line_color = data_series?.line_style?.stroke;
+            if (!line_color) {
+                const first_cv = Array.isArray(data_series?.color_values)
+                    ? data_series?.color_values?.find((color_val) => color_val != null)
+                    : undefined;
+                /* oxlint-disable @typescript-eslint/prefer-nullish-coalescing -- empty-string colors should fall through */
+                line_color =
+                    (first_cv != null ? color_scale_fn(first_cv) : undefined) ||
+                        first_point_style?.fill ||
+                        first_point_style?.stroke ||
+                        series_default_color;
+                /* oxlint-enable @typescript-eslint/prefer-nullish-coalescing */
+            }
+            display_style.line_color = line_color;
+            display_style.line_dash = data_series?.line_style?.line_dash;
+        }
+        else {
+            // No line marker: no line swatch in the legend
+            display_style.line_dash = undefined;
+            display_style.line_color = undefined;
+        }
+        return {
+            series_idx,
+            label: explicit_label ?? `Series ${series_idx + 1}`,
+            visible: data_series?.visible ?? true,
+            display_style,
+            has_explicit_label: explicit_label != null,
+            legend_group: data_series?.legend_group,
+        };
+    });
+    // Deduplicate by legend_group::label (first occurrence wins, across series + fills)
+    const seen_labels = new Set();
+    const first_seen = (group, label) => {
+        const key = `${group ?? ``}::${label ?? ``}`;
+        if (seen_labels.has(key))
+            return false;
+        seen_labels.add(key);
+        return true;
+    };
+    const series_items = items.filter((item) => first_seen(item.legend_group, item.label));
+    const fill_items = computed_fills
+        .filter((fill) => fill.show_in_legend !== false && fill.label)
+        .filter((fill) => first_seen(fill.legend_group, fill.label))
+        .map((fill) => {
+        // Pass gradient for swatch rendering, or solid color as fallback
+        const fill_gradient = is_fill_gradient(fill.fill) ? fill.fill : undefined;
+        const fill_color = typeof fill.fill === `string` ? fill.fill : undefined;
+        return {
+            series_idx: -1, // Not a series
+            fill_idx: fill.idx,
+            fill_source_type: fill.source_type,
+            fill_source_idx: fill.source_idx,
+            item_type: `fill`,
+            label: fill.label ?? ``,
+            visible: fill.visible !== false,
+            legend_group: fill.legend_group,
+            display_style: {
+                fill_color,
+                fill_opacity: fill.fill_opacity ?? 0.3,
+                edge_color: fill.edge_upper?.color,
+                fill_gradient,
+            },
+        };
+    });
+    return [...series_items, ...fill_items];
+}
+const is_transparent_or_none = (color) => !color ||
+    color === `none` ||
+    color === `transparent` ||
+    /rgba\([^)]+[,/]\s*0(\.0*)?\s*\)$/.test(color);
+// Type-guard negation of is_transparent_or_none so usable colors narrow to string
+const is_opaque_color = (color) => !is_transparent_or_none(color);
+// Resolve tooltip background color: point color-scale value, then point fill, then point
+// stroke (points marker), then line color cascade (line marker), then dark fallback
+export function pick_tooltip_bg(point, series, color_scale_fn) {
+    const { color_value, point_style } = point;
+    const series_markers = series?.markers ?? DEFAULT_MARKERS;
+    const scale_color = color_value != null ? color_scale_fn(color_value) : undefined;
+    if (is_opaque_color(scale_color))
+        return scale_color;
+    const fill_color = point_style?.fill;
+    if (is_opaque_color(fill_color))
+        return fill_color;
+    if (series_markers?.includes(`points`)) {
+        const stroke_color = point_style?.stroke;
+        if (is_opaque_color(stroke_color))
+            return stroke_color;
+    }
+    if (series_markers?.includes(`line`)) {
+        const line_style = series?.line_style ?? {};
+        const first_point_style = Array.isArray(series?.point_style)
+            ? series?.point_style[0]
+            : series?.point_style;
+        const first_color_value = series?.color_values?.[0];
+        let line_color_candidate = line_style.stroke;
+        if (is_transparent_or_none(line_color_candidate)) {
+            line_color_candidate = first_point_style?.fill;
+        }
+        if (is_transparent_or_none(line_color_candidate) && first_color_value != null)
+            line_color_candidate = color_scale_fn(first_color_value);
+        if (is_transparent_or_none(line_color_candidate) && series_markers?.includes(`points`))
+            line_color_candidate = first_point_style?.stroke;
+        if (is_opaque_color(line_color_candidate))
+            return line_color_candidate;
+    }
+    return `rgba(0, 0, 0, 0.7)`;
+}