matterviz 0.3.6 → 0.4.0

package/dist/plot/core/types.js

@@ -0,0 +1,99 @@
+// Type guard for select value narrowing (avoids unsafe casts)
+const SCALE_TYPE_NAMES = new Set([`linear`, `log`, `arcsinh`, `time`]);
+export const is_scale_type_name = (val) => SCALE_TYPE_NAMES.has(val);
+// Helper to normalize ScaleType to base type name
+export function get_scale_type_name(scale_type) {
+    if (!scale_type)
+        return `linear`;
+    if (typeof scale_type === `string`)
+        return scale_type;
+    return scale_type.type;
+}
+// Helper to get arcsinh threshold (returns 1 as default for non-arcsinh scales)
+export function get_arcsinh_threshold(scale_type) {
+    if (!scale_type)
+        return 1;
+    if (typeof scale_type === `object` && scale_type.type === `arcsinh`) {
+        const threshold = scale_type.threshold ?? 1;
+        if (!Number.isFinite(threshold) || threshold <= 0) {
+            throw new Error(`arcsinh threshold must be a positive finite number, got ${threshold}`);
+        }
+        return threshold;
+    }
+    return 1; // default threshold
+}
+// Helper to detect time scale - checks explicit scale_type or falls back to format heuristic
+// Prefer explicit scale_type: 'time' for new code; format heuristic kept for backwards compatibility
+export function is_time_scale(scale_type, format) {
+    if (get_scale_type_name(scale_type) === `time`)
+        return true;
+    // Fallback: d3 time format strings start with '%'
+    return format?.startsWith(`%`) ?? false;
+}
+// Type guard for select value narrowing (avoids unsafe casts)
+const Y2_SYNC_MODES = new Set([`none`, `synced`, `align`]);
+export const is_y2_sync_mode = (val) => Y2_SYNC_MODES.has(val);
+export const LINE_TYPES = [`solid`, `dashed`, `dotted`];
+// Define grid cell identifiers
+export const CELLS_3X3 = [
+    `top-left`,
+    `top-center`,
+    `top-right`,
+    `middle-left`,
+    `middle-center`,
+    `middle-right`,
+    `bottom-left`,
+    `bottom-center`,
+    `bottom-right`,
+];
+export const CORNER_CELLS = [`top-left`, `top-right`, `bottom-left`, `bottom-right`];
+// Default grid line style (SSOT for all plot components)
+export const DEFAULT_GRID_STYLE = {
+    stroke: `var(--border-color, gray)`,
+    'stroke-dasharray': `4`,
+    'stroke-width': `0.5`,
+};
+export const DEFAULT_MARKERS = `line+points`;
+// Default series colors for auto-differentiation (similar to d3 schemeTableau10)
+export const DEFAULT_SERIES_COLORS = [
+    `#4e79a7`, // blue
+    `#f28e2c`, // orange
+    `#e15759`, // red
+    `#76b7b2`, // teal
+    `#59a14f`, // green
+    `#edc949`, // yellow
+    `#af7aa1`, // purple
+    `#ff9da7`, // pink
+    `#9c755f`, // brown
+    `#bab0ab`, // gray
+];
+// Default series symbols for auto-differentiation (cycling through distinct shapes)
+export const DEFAULT_SERIES_SYMBOLS = [
+    `Circle`,
+    `Square`,
+    `Triangle`,
+    `Cross`,
+    `Diamond`,
+    `Star`,
+    `Wye`,
+];
+// Curve types supported for fill path generation (matching d3-shape curves)
+export const FILL_CURVE_TYPES = [
+    `linear`,
+    `monotoneX`,
+    `monotoneY`,
+    `step`,
+    `stepBefore`,
+    `stepAfter`,
+    `basis`,
+    `cardinal`,
+    `catmullRom`,
+    `natural`,
+];
+// Default style values for reference lines
+export const REF_LINE_STYLE_DEFAULTS = {
+    color: `currentColor`,
+    width: 1,
+    dash: ``,
+    opacity: 1,
+};

package/dist/plot/core/utils/label-placement.d.ts

@@ -0,0 +1,68 @@
+import type { Point2D } from '../../../math';
+import type { AxisConfig, DataSeries } from '../..';
+import type { PlotScaleFn } from '../scales';
+import type { LabelPlacementConfig, LabelPlacementWeights } from '../types';
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface PlotBounds {
+    min_x: number;
+    min_y: number;
+    max_x: number;
+    max_y: number;
+}
+interface AnchorInfo {
+    x: number;
+    y: number;
+    radius: number;
+}
+interface LabelState extends Rect {
+    anchor_idx: number;
+}
+export interface LabelSize {
+    width: number;
+    height: number;
+}
+export interface LeaderLineSegment {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+export interface LeaderLineOptions {
+    point: Point2D;
+    point_radius: number;
+    label_center: Point2D;
+    label_size: LabelSize;
+    min_length?: number;
+    label_padding?: number;
+}
+export declare function parse_font_size(size_str?: string): number;
+export declare function estimate_label_size(text: string, font_size_str?: string): LabelSize;
+export declare function rect_overlap_area(a: Rect, b: Rect): number;
+export declare function rect_circle_overlap(rect: Rect, cx: number, cy: number, radius: number): number;
+export declare function segments_intersect(ax1: number, ay1: number, ax2: number, ay2: number, bx1: number, by1: number, bx2: number, by2: number): boolean;
+export declare function segment_rect_intersects(sx1: number, sy1: number, sx2: number, sy2: number, rect: Rect): boolean;
+export declare function rect_out_of_bounds_area(rect: Rect, bounds: PlotBounds): number;
+export declare function label_leader_segment({ point, point_radius, label_center, label_size, min_length, label_padding, }: LeaderLineOptions): LeaderLineSegment | null;
+export declare function generate_candidates(ax: number, ay: number, point_radius: number, label_w: number, label_h: number, gap: number): Point2D[];
+export declare function compute_delta_energy(labels: LabelState[], anchors: AnchorInfo[], changed_idx: number, old_state: LabelState, new_state: LabelState, weights: Required<LabelPlacementWeights>, bounds: PlotBounds): number;
+export declare function compute_label_positions(filtered_series: DataSeries[], config: LabelPlacementConfig, scales: {
+    x_scale_fn: PlotScaleFn;
+    y_scale_fn: PlotScaleFn;
+    y2_scale_fn: PlotScaleFn;
+    x_axis: AxisConfig;
+}, bounds: {
+    width: number;
+    height: number;
+    pad: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+}): Record<string, Point2D>;
+export {};

package/dist/plot/core/utils/label-placement.js

@@ -0,0 +1,326 @@
+import { is_time_scale } from '../types';
+const DEFAULT_WEIGHTS = {
+    overlap: 30,
+    marker: 100,
+    leader_cross: 10,
+    leader_text: 8,
+    distance: 0.5,
+    bounds: 100,
+};
+const NEIGHBOR_CELL_OFFSETS = [-1, 0, 1];
+const copy_state = (target, source) => {
+    target.x = source.x;
+    target.y = source.y;
+    target.w = source.w;
+    target.h = source.h;
+    target.anchor_idx = source.anchor_idx;
+};
+export function parse_font_size(size_str) {
+    if (!size_str)
+        return 12;
+    const match = /^(\d+(?:\.\d+)?)(px|em|rem)?$/.exec(size_str);
+    if (!match)
+        return 12;
+    const value = parseFloat(match[1]);
+    return match[2] === `em` || match[2] === `rem` ? value * 16 : value;
+}
+export function estimate_label_size(text, font_size_str) {
+    const font_size = parse_font_size(font_size_str);
+    const label_lines = text.split(/\r?\n/);
+    const max_line_length = Math.max(...label_lines.map((line) => line.length));
+    return {
+        width: max_line_length * font_size * 0.6 + 10,
+        height: label_lines.length * font_size * 1.2,
+    };
+}
+// === Geometry helpers ===
+export function rect_overlap_area(a, b) {
+    const ox = Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x));
+    const oy = Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+    return ox * oy;
+}
+export function rect_circle_overlap(rect, cx, cy, radius) {
+    // Inflate rect by radius to create an exclusion zone around the marker
+    const left = rect.x - radius;
+    const top = rect.y - radius;
+    const right = rect.x + rect.w + radius;
+    const bottom = rect.y + rect.h + radius;
+    if (cx < left || cx > right || cy < top || cy > bottom)
+        return 0;
+    // Penalty proportional to how deep the marker center is inside the exclusion zone
+    const dx = Math.min(cx - left, right - cx);
+    const dy = Math.min(cy - top, bottom - cy);
+    return Math.min(dx, dy) + radius;
+}
+export function segments_intersect(ax1, ay1, ax2, ay2, bx1, by1, bx2, by2) {
+    const d1x = ax2 - ax1, d1y = ay2 - ay1;
+    const d2x = bx2 - bx1, d2y = by2 - by1;
+    const cross = d1x * d2y - d1y * d2x;
+    if (Math.abs(cross) < 1e-10)
+        return false;
+    const t_val = ((bx1 - ax1) * d2y - (by1 - ay1) * d2x) / cross;
+    const u_val = ((bx1 - ax1) * d1y - (by1 - ay1) * d1x) / cross;
+    return t_val > 0 && t_val < 1 && u_val > 0 && u_val < 1;
+}
+export function segment_rect_intersects(sx1, sy1, sx2, sy2, rect) {
+    const rx = rect.x, ry = rect.y, rx2 = rx + rect.w, ry2 = ry + rect.h;
+    return (segments_intersect(sx1, sy1, sx2, sy2, rx, ry, rx2, ry) ||
+        segments_intersect(sx1, sy1, sx2, sy2, rx2, ry, rx2, ry2) ||
+        segments_intersect(sx1, sy1, sx2, sy2, rx, ry2, rx2, ry2) ||
+        segments_intersect(sx1, sy1, sx2, sy2, rx, ry, rx, ry2));
+}
+export function rect_out_of_bounds_area(rect, bounds) {
+    let penalty = 0;
+    if (rect.x < bounds.min_x)
+        penalty += (bounds.min_x - rect.x) * rect.h;
+    if (rect.y < bounds.min_y)
+        penalty += (bounds.min_y - rect.y) * rect.w;
+    if (rect.x + rect.w > bounds.max_x)
+        penalty += (rect.x + rect.w - bounds.max_x) * rect.h;
+    if (rect.y + rect.h > bounds.max_y)
+        penalty += (rect.y + rect.h - bounds.max_y) * rect.w;
+    return penalty;
+}
+export function label_leader_segment({ point, point_radius, label_center, label_size, min_length = 6, label_padding = 1, }) {
+    const delta_x = label_center.x - point.x;
+    const delta_y = label_center.y - point.y;
+    const center_distance = Math.hypot(delta_x, delta_y);
+    if (center_distance <= 0)
+        return null;
+    const unit_x = delta_x / center_distance;
+    const unit_y = delta_y / center_distance;
+    const start_x = point.x + unit_x * point_radius;
+    const start_y = point.y + unit_y * point_radius;
+    const half_width = label_size.width / 2 + label_padding;
+    const half_height = label_size.height / 2 + label_padding;
+    const edge_distance = Math.min(Math.abs(unit_x) > 0.001 ? half_width / Math.abs(unit_x) : Infinity, Math.abs(unit_y) > 0.001 ? half_height / Math.abs(unit_y) : Infinity);
+    const visible_length = center_distance - point_radius - edge_distance;
+    if (visible_length <= min_length)
+        return null;
+    const end_x = label_center.x - unit_x * edge_distance;
+    const end_y = label_center.y - unit_y * edge_distance;
+    return { x1: start_x, y1: start_y, x2: end_x, y2: end_y };
+}
+// 8 candidate positions around anchor: R, TR, T, TL, L, BL, B, BR
+// Positions are top-left corner of the label bounding box.
+// All positions keep a full `offset` gap from the marker edge.
+export function generate_candidates(ax, ay, point_radius, label_w, label_h, gap) {
+    const offset = point_radius + gap;
+    return [
+        { x: ax + offset, y: ay - label_h + offset / 2 }, // R  (baseline just below center)
+        { x: ax + offset, y: ay - label_h - offset / 2 }, // TR
+        { x: ax - label_w / 2, y: ay - label_h - offset }, // T
+        { x: ax - label_w - offset, y: ay - label_h - offset / 2 }, // TL
+        { x: ax - label_w - offset, y: ay - label_h + offset / 2 }, // L  (baseline just below center)
+        { x: ax - label_w - offset, y: ay + offset / 2 }, // BL
+        { x: ax - label_w / 2, y: ay + offset }, // B
+        { x: ax + offset, y: ay + offset / 2 }, // BR
+    ];
+}
+// Compute energy delta when only label at `changed_idx` moves
+export function compute_delta_energy(labels, anchors, changed_idx, old_state, new_state, weights, bounds) {
+    let delta = 0;
+    const anchor = anchors[new_state.anchor_idx];
+    const old_cx = old_state.x + old_state.w / 2, old_cy = old_state.y + old_state.h / 2;
+    const new_cx = new_state.x + new_state.w / 2, new_cy = new_state.y + new_state.h / 2;
+    // Distance penalty change
+    delta +=
+        weights.distance *
+            (Math.hypot(new_cx - anchor.x, new_cy - anchor.y) -
+                Math.hypot(old_cx - anchor.x, old_cy - anchor.y));
+    // Bounds penalty change
+    delta +=
+        weights.bounds *
+            (rect_out_of_bounds_area(new_state, bounds) - rect_out_of_bounds_area(old_state, bounds));
+    // Marker overlap change (all markers)
+    for (const marker of anchors) {
+        delta +=
+            weights.marker *
+                (rect_circle_overlap(new_state, marker.x, marker.y, marker.radius) -
+                    rect_circle_overlap(old_state, marker.x, marker.y, marker.radius));
+    }
+    // Pairwise interactions with all other labels
+    for (let jdx = 0; jdx < labels.length; jdx++) {
+        if (jdx === changed_idx)
+            continue;
+        const other = labels[jdx];
+        const anchor_j = anchors[other.anchor_idx];
+        const other_cx = other.x + other.w / 2, other_cy = other.y + other.h / 2;
+        // Label-label overlap delta
+        delta +=
+            weights.overlap *
+                (rect_overlap_area(new_state, other) - rect_overlap_area(old_state, other));
+        // Leader line crossing delta (changed label's leader vs other's leader)
+        const old_cross = segments_intersect(anchor.x, anchor.y, old_cx, old_cy, anchor_j.x, anchor_j.y, other_cx, other_cy);
+        const new_cross = segments_intersect(anchor.x, anchor.y, new_cx, new_cy, anchor_j.x, anchor_j.y, other_cx, other_cy);
+        if (new_cross !== old_cross)
+            delta += (new_cross ? 1 : -1) * weights.leader_cross;
+        // Changed label's leader crossing other label's rect
+        const old_text = segment_rect_intersects(anchor.x, anchor.y, old_cx, old_cy, other);
+        const new_text = segment_rect_intersects(anchor.x, anchor.y, new_cx, new_cy, other);
+        if (new_text !== old_text)
+            delta += (new_text ? 1 : -1) * weights.leader_text;
+        // Other label's leader crossing changed label's rect
+        const old_other = segment_rect_intersects(anchor_j.x, anchor_j.y, other_cx, other_cy, old_state);
+        const new_other = segment_rect_intersects(anchor_j.x, anchor_j.y, other_cx, other_cy, new_state);
+        if (new_other !== old_other)
+            delta += (new_other ? 1 : -1) * weights.leader_text;
+    }
+    return delta;
+}
+function cull_dense_labels(label_infos, max_neighbors, radius) {
+    if (radius <= 0 || label_infos.length <= max_neighbors + 1)
+        return label_infos;
+    const radius_squared = radius * radius;
+    const get_cell = (value) => Math.floor(value / radius);
+    const grid = {};
+    label_infos.forEach(({ anchor }, label_idx) => {
+        const key = `${get_cell(anchor.x)},${get_cell(anchor.y)}`;
+        const bucket = grid[key] ?? (grid[key] = []);
+        bucket.push(label_idx);
+    });
+    return label_infos.filter(({ anchor }, label_idx) => {
+        const cell_x = get_cell(anchor.x);
+        const cell_y = get_cell(anchor.y);
+        let neighbors = 0;
+        for (const cell_x_offset of NEIGHBOR_CELL_OFFSETS) {
+            for (const cell_y_offset of NEIGHBOR_CELL_OFFSETS) {
+                const bucket = grid[`${cell_x + cell_x_offset},${cell_y + cell_y_offset}`];
+                if (!bucket)
+                    continue;
+                for (const neighbor_idx of bucket) {
+                    if (neighbor_idx === label_idx)
+                        continue;
+                    const delta_x = anchor.x - label_infos[neighbor_idx].anchor.x;
+                    const delta_y = anchor.y - label_infos[neighbor_idx].anchor.y;
+                    if (delta_x * delta_x + delta_y * delta_y <= radius_squared)
+                        neighbors += 1;
+                    if (neighbors > max_neighbors)
+                        return false;
+                }
+            }
+        }
+        return true;
+    });
+}
+// === Main export ===
+export function compute_label_positions(filtered_series, config, scales, bounds) {
+    const { x_scale_fn, y_scale_fn, y2_scale_fn, x_axis } = scales;
+    const { width, height, pad } = bounds;
+    const plot_bounds = {
+        min_x: pad.l,
+        min_y: pad.t,
+        max_x: width - pad.r,
+        max_y: height - pad.b,
+    };
+    // Collect all label data in a single pass
+    let label_infos = [];
+    const candidate_gap = config.candidate_gap ?? 4;
+    for (const series of filtered_series) {
+        for (const pt of series.filtered_data ?? []) {
+            if (!pt.point_label?.auto_placement || !pt.point_label.text)
+                continue;
+            const ax = is_time_scale(x_axis.scale_type, x_axis.format)
+                ? x_scale_fn(new Date(pt.x))
+                : x_scale_fn(pt.x);
+            const ay = (series.y_axis === `y2` ? y2_scale_fn : y_scale_fn)(pt.y);
+            const label_size = pt.point_label.size ??
+                estimate_label_size(pt.point_label.text, pt.point_label.font_size);
+            const label_w = label_size.width;
+            const label_h = label_size.height;
+            const radius = pt.point_style?.radius ?? 3;
+            label_infos.push({
+                id: `${pt.series_idx}-${pt.point_idx}`,
+                anchor: { x: ax, y: ay, radius },
+                width: label_w,
+                height: label_h,
+                candidates: generate_candidates(ax, ay, radius, label_w, label_h, candidate_gap),
+            });
+        }
+    }
+    if (config.max_neighbors) {
+        label_infos = cull_dense_labels(label_infos, config.max_neighbors.count, config.max_neighbors.radius);
+    }
+    const num_labels = label_infos.length;
+    if (num_labels === 0)
+        return {};
+    // Fallback: too many labels, just offset to the right with bounds clamping
+    if (config.max_labels && num_labels > config.max_labels) {
+        return Object.fromEntries(label_infos.map((info) => [
+            info.id,
+            {
+                x: Math.min(Math.max(info.anchor.x + 5, plot_bounds.min_x), plot_bounds.max_x - info.width),
+                y: Math.min(Math.max(info.anchor.y, plot_bounds.min_y), plot_bounds.max_y - info.height),
+            },
+        ]));
+    }
+    const weights = { ...DEFAULT_WEIGHTS, ...config.weights };
+    const anchors = label_infos.map((info) => info.anchor);
+    // Greedy initialization: pick best candidate per label
+    const labels = [];
+    for (let idx = 0; idx < num_labels; idx++) {
+        const { candidates, width: lw, height: lh, anchor } = label_infos[idx];
+        let best_candidate = candidates[0];
+        let best_score = Infinity;
+        for (const candidate of candidates) {
+            const test_rect = { x: candidate.x, y: candidate.y, w: lw, h: lh };
+            let score = weights.bounds * rect_out_of_bounds_area(test_rect, plot_bounds);
+            for (const placed of labels) {
+                score += weights.overlap * rect_overlap_area(test_rect, placed);
+            }
+            for (const marker of anchors) {
+                score +=
+                    weights.marker * rect_circle_overlap(test_rect, marker.x, marker.y, marker.radius);
+            }
+            score +=
+                weights.distance *
+                    Math.hypot(candidate.x + lw / 2 - anchor.x, candidate.y + lh / 2 - anchor.y);
+            if (score < best_score) {
+                best_score = score;
+                best_candidate = candidate;
+            }
+        }
+        labels.push({ x: best_candidate.x, y: best_candidate.y, w: lw, h: lh, anchor_idx: idx });
+    }
+    // Simulated annealing
+    const sa_iterations = config.sa_iterations ?? 2000;
+    const total_steps = sa_iterations * num_labels;
+    const cooling_rate = 1 / total_steps;
+    // Seeded pseudo-random for deterministic results
+    let rng_state = 42;
+    const next_random = () => {
+        rng_state = (rng_state * 1664525 + 1013904223) & 0x7fffffff;
+        return rng_state / 0x7fffffff;
+    };
+    // Reusable scratch objects to avoid allocations in the hot loop
+    const old_scratch = { x: 0, y: 0, w: 0, h: 0, anchor_idx: 0 };
+    const new_scratch = { x: 0, y: 0, w: 0, h: 0, anchor_idx: 0 };
+    for (let step = 0; step < total_steps; step++) {
+        const temperature = Math.max(0.001, 1.0 - step * cooling_rate);
+        const label_idx = Math.floor(next_random() * num_labels);
+        const current = labels[label_idx];
+        copy_state(old_scratch, current);
+        copy_state(new_scratch, current);
+        // 70% try a candidate position, 30% small perturbation
+        if (next_random() < 0.7) {
+            const candidate = label_infos[label_idx].candidates[Math.floor(next_random() * label_infos[label_idx].candidates.length)];
+            new_scratch.x = candidate.x;
+            new_scratch.y = candidate.y;
+        }
+        else {
+            const max_shift = 30 * temperature + 5;
+            new_scratch.x += (next_random() - 0.5) * 2 * max_shift;
+            new_scratch.y += (next_random() - 0.5) * 2 * max_shift;
+        }
+        const delta = compute_delta_energy(labels, anchors, label_idx, old_scratch, new_scratch, weights, plot_bounds);
+        if (delta < 0 || next_random() < Math.exp(-delta / (temperature * 10 + 0.1))) {
+            current.x = new_scratch.x;
+            current.y = new_scratch.y;
+        }
+    }
+    // Return label center positions (matching existing API)
+    return Object.fromEntries(labels.map((label, idx) => [
+        label_infos[idx].id,
+        { x: label.x + label.w / 2, y: label.y + label.h / 2 },
+    ]));
+}

package/dist/plot/core/utils/series-visibility.d.ts

@@ -0,0 +1,26 @@
+type VisSeries = {
+    label?: string | null;
+    unit?: string;
+    y_axis?: string;
+    visible?: boolean;
+    x?: unknown;
+    y?: unknown;
+};
+type SeriesSource = [string, string, string, ...unknown[]];
+export type SeriesVisibilitySnapshot = {
+    visibility: boolean[];
+    source: SeriesSource[];
+};
+export declare function have_compatible_units(series1: VisSeries, series2: VisSeries): boolean;
+export declare function toggle_series_visibility<Series extends VisSeries>(series: Series[], series_idx: number): Series[];
+export declare function toggle_group_visibility<Series extends VisSeries>(series: Series[], series_indices: number[]): Series[];
+export declare function handle_legend_double_click<Series extends VisSeries>(series: Series[], idx: number, prev_snapshot: SeriesVisibilitySnapshot | null): {
+    series: Series[];
+    prev_visibility: SeriesVisibilitySnapshot | null;
+};
+export declare function create_legend_visibility<Series extends VisSeries>(get_series: () => Series[], set_series: (series: Series[]) => void): {
+    on_toggle: (series_idx: number) => void;
+    on_group_toggle: (group_name: string, series_indices: number[]) => void;
+    on_double_click: (series_idx: number) => void;
+};
+export {};

package/dist/plot/core/utils/series-visibility.js

@@ -0,0 +1,112 @@
+// Length + first/last element: a by-value signature for x/y data. Deliberately NOT
+// array identity: inside components those are $state proxies whose identity changes
+// when the series prop is reassigned (e.g. by the isolate itself), which made the
+// snapshot reject itself and permanently broke restore-from-isolation.
+const data_sig = (arr) => Array.isArray(arr) ? [arr.length, arr[0], arr[arr.length - 1]] : [arr];
+const series_source = (series, length = series.length) => series
+    .slice(0, length)
+    .map((srs) => [
+    srs.label ?? ``,
+    srs.unit ?? ``,
+    srs.y_axis ?? ``,
+    ...data_sig(srs.x),
+    ...data_sig(srs.y),
+]);
+const same_series_source = (series, snapshot_series) => series.length === snapshot_series.length &&
+    series.every((source, idx) => source.length === snapshot_series[idx].length &&
+        source.every((part, part_idx) => Object.is(part, snapshot_series[idx][part_idx])));
+export function have_compatible_units(series1, series2) {
+    if (!series1.unit || !series2.unit)
+        return true;
+    return series1.unit === series2.unit;
+}
+export function toggle_series_visibility(series, series_idx) {
+    if (series_idx < 0 || series_idx >= series.length || !series[series_idx])
+        return series;
+    const toggled = series[series_idx];
+    const new_visibility = !(toggled.visible ?? true);
+    const target_axis = toggled.y_axis ?? `y1`;
+    return series.map((srs, idx) => {
+        if ((toggled.label && srs.label === toggled.label) ||
+            (idx === series_idx && !toggled.label)) {
+            return { ...srs, visible: new_visibility };
+        }
+        if (new_visibility && (srs.y_axis ?? `y1`) === target_axis) {
+            if (!have_compatible_units(toggled, srs) && (srs.visible ?? true)) {
+                return { ...srs, visible: false };
+            }
+        }
+        return srs;
+    });
+}
+export function toggle_group_visibility(series, series_indices) {
+    // Filter to valid indices upfront
+    const valid_indices = series_indices.filter((idx) => idx >= 0 && idx < series.length);
+    if (valid_indices.length === 0)
+        return series;
+    const idx_set = new Set(valid_indices);
+    // Check if all series in the group are currently visible
+    const all_visible = valid_indices.every((idx) => series[idx].visible ?? true);
+    // Toggle: if all visible, hide all; otherwise show all
+    const new_visibility = !all_visible;
+    return series.map((srs, idx) => idx_set.has(idx) ? { ...srs, visible: new_visibility } : srs);
+}
+export function handle_legend_double_click(series, idx, prev_snapshot) {
+    if (idx < 0 || idx >= series.length) {
+        return { series, prev_visibility: prev_snapshot };
+    }
+    const { label } = series[idx];
+    const current = series.map((srs) => srs.visible ?? true);
+    const current_source = prev_snapshot
+        ? series_source(series, prev_snapshot.visibility.length)
+        : [];
+    const prev_visibility = prev_snapshot && same_series_source(current_source, prev_snapshot.source)
+        ? prev_snapshot.visibility
+        : null;
+    // Only check original series (ignore new ones added after isolation)
+    const check_series = prev_visibility ? series.slice(0, prev_visibility.length) : series;
+    const is_isolated = check_series.every((srs, srs_idx) => {
+        const in_group = label ? srs.label === label : srs_idx === idx;
+        return in_group ? (srs.visible ?? true) : !(srs.visible ?? true);
+    });
+    // Restore from isolation
+    if (is_isolated && prev_visibility) {
+        return {
+            series: series.map((srs, srs_idx) => srs_idx < prev_visibility.length && current[srs_idx] !== prev_visibility[srs_idx]
+                ? { ...srs, visible: prev_visibility[srs_idx] }
+                : srs),
+            prev_visibility: null,
+        };
+    }
+    // Isolate series
+    const new_prev = prev_visibility
+        ? prev_snapshot
+        : current.filter(Boolean).length > 1
+            ? {
+                visibility: [...current],
+                source: series_source(series),
+            }
+            : null;
+    return {
+        series: series.map((srs, srs_idx) => {
+            const in_group = label ? srs.label === label : srs_idx === idx;
+            return (srs.visible ?? true) !== in_group ? { ...srs, visible: in_group } : srs;
+        }),
+        prev_visibility: new_prev,
+    };
+}
+// Bundle the three legend visibility handlers (click toggle, group toggle,
+// double-click isolate/restore) around a series accessor pair. Owns the
+// isolate/restore snapshot internally so components don't each carry it.
+export function create_legend_visibility(get_series, set_series) {
+    let prev_visibility = null;
+    return {
+        on_toggle: (series_idx) => set_series(toggle_series_visibility(get_series(), series_idx)),
+        on_group_toggle: (_group_name, series_indices) => set_series(toggle_group_visibility(get_series(), series_indices)),
+        on_double_click: (series_idx) => {
+            const result = handle_legend_double_click(get_series(), series_idx, prev_visibility);
+            set_series(result.series);
+            prev_visibility = result.prev_visibility;
+        },
+    };
+}

package/dist/plot/core/utils.d.ts

@@ -0,0 +1,11 @@
+import type { TweenOptions } from 'svelte/motion';
+export declare const unique_id: (prefix?: string) => string;
+export declare const LINE_TWEEN: {
+    max_series: number;
+    max_points: number;
+};
+export declare const resolve_line_tween: (line_tween: TweenOptions<string> | undefined, load: {
+    series: number;
+    points: number;
+}) => TweenOptions<string> | undefined;
+export declare function calc_auto_range(values: number[]): [number, number];

package/dist/plot/core/utils.js

@@ -0,0 +1,27 @@
+// Unique DOM id token (for SVG clipPath/gradient ids, control `for`/`id` prefixes). Returns a
+// fresh id on every call; callers should store it in a const (e.g. `const id = unique_id('foo')`)
+// so it stays stable across re-renders. Pass a prefix for a readable `prefix-<uuid>`, or omit it
+// when the caller adds its own prefix.
+export const unique_id = (prefix = ``) => prefix ? `${prefix}-${crypto.randomUUID()}` : crypto.randomUUID();
+// Path-morph (interpolatePath) tweening scales poorly with many simultaneously morphing
+// <path> elements (band structures with 100+ bands) or a single very long line. Disable
+// the morph above these budgets unless the caller explicitly opts into a tween.
+export const LINE_TWEEN = { max_series: 16, max_points: 8000 };
+export const resolve_line_tween = (line_tween, load) => line_tween ??
+    (load.series > LINE_TWEEN.max_series || load.points > LINE_TWEEN.max_points
+        ? { duration: 0 }
+        : undefined);
+export function calc_auto_range(values) {
+    const finite_values = values.filter(Number.isFinite);
+    if (finite_values.length === 0)
+        return [0, 1];
+    let [min_value, max_value] = [finite_values[0], finite_values[0]];
+    for (const value of finite_values) {
+        if (value < min_value)
+            min_value = value;
+        else if (value > max_value)
+            max_value = value;
+    }
+    const padding = (max_value - min_value) * 0.05 || 0.5;
+    return [min_value - padding, max_value + padding];
+}