matterviz 0.3.7 → 0.4.1

package/dist/plot/core/fill-utils.js

@@ -0,0 +1,391 @@
+// Fill-between utility functions for ScatterPlot fill regions
+// Each fill edge is traced through its boundary's own points with the same curve the series line
+// uses (curveMonotoneX), so an unclipped fill edge coincides with the line it borders. When an
+// edge is clipped (x_range / partial overlap), the inserted endpoint shifts the neighboring
+// monotone tangent, so the clipped edge can deviate sub-pixel from the full series line.
+import { curveBasis, curveCardinal, curveCatmullRom, curveLinear, curveMonotoneX, curveMonotoneY, curveNatural, curveStep, curveStepAfter, curveStepBefore, line, } from 'd3-shape';
+// Epsilon value for log scale clamping (to avoid log(0) = -Infinity)
+export const LOG_EPSILON = 1e-10;
+// Resolves a series reference (by index or id) to the actual DataSeries
+export function resolve_series_ref(ref, series) {
+    if (`series_idx` in ref && typeof ref.series_idx === `number`) {
+        const idx = ref.series_idx;
+        return idx >= 0 && idx < series.length ? series[idx] : null;
+    }
+    if (`series_id` in ref && ref.series_id !== undefined) {
+        return series.find((data_series) => data_series.id === ref.series_id) ?? null;
+    }
+    return null;
+}
+// === Monotone-cubic interpolation matching d3's curveMonotoneX ===
+// Used to evaluate a boundary's y on its own curve (for endpoint clipping and where-condition
+// detection) so interpolated points lie exactly on the rendered line.
+// Mirrors d3-shape's own sign helper (returns 1 for 0, unlike Math.sign) so
+// monotone_tangents reproduces curveMonotoneX exactly. Do NOT change to return 0
+// for 0: that would diverge from the rendered curve. It's harmless either way here
+// since s0/s1 === 0 forces the Math.min term below to 0 regardless.
+const sign = (val) => (val < 0 ? -1 : 1);
+// Per-knot tangents reproducing d3 curveMonotoneX (slope3 interior, slope2 endpoints)
+function monotone_tangents(xs, ys) {
+    const num = xs.length;
+    if (num <= 1)
+        return Array(num).fill(0);
+    const secant = (idx) => (ys[idx + 1] - ys[idx]) / (xs[idx + 1] - xs[idx]);
+    if (num === 2) {
+        const slope = secant(0);
+        const safe = Number.isFinite(slope) ? slope : 0;
+        return [safe, safe];
+    }
+    const tangents = Array.from({ length: num }, () => 0);
+    for (let idx = 1; idx < num - 1; idx++) {
+        const h0 = xs[idx] - xs[idx - 1];
+        const h1 = xs[idx + 1] - xs[idx];
+        const s0 = (ys[idx] - ys[idx - 1]) / (h0 || (h1 < 0 ? -0 : 0));
+        const s1 = (ys[idx + 1] - ys[idx]) / (h1 || (h0 < 0 ? -0 : 0));
+        const par = (s0 * h1 + s1 * h0) / (h0 + h1);
+        tangents[idx] =
+            (sign(s0) + sign(s1)) * Math.min(Math.abs(s0), Math.abs(s1), 0.5 * Math.abs(par)) || 0;
+    }
+    tangents[0] = (3 * secant(0) - tangents[1]) / 2;
+    tangents[num - 1] = (3 * secant(num - 2) - tangents[num - 2]) / 2;
+    return tangents;
+}
+// Index of the bracket [lo, lo+1] containing x (xs ascending); clamps to interior brackets
+const bracket = (xs, x) => {
+    let lo = 0;
+    let hi = xs.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (xs[mid] <= x)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return lo;
+};
+// y clamped to the endpoint value when x is at/outside the domain (null when x is strictly inside)
+const endpoint_clamp = (xs, ys, x) => {
+    if (xs.length === 0)
+        return NaN;
+    if (x <= xs[0])
+        return ys[0];
+    if (x >= xs[xs.length - 1])
+        return ys[xs.length - 1];
+    return null;
+};
+// Evaluate the d3 curveMonotoneX through (xs, ys) at x (xs ascending). Clamps outside the domain.
+export function monotone_interpolate(xs, ys, x, tangents) {
+    const edge = endpoint_clamp(xs, ys, x);
+    if (edge !== null)
+        return edge;
+    const lo = bracket(xs, x);
+    const [x0, x1] = [xs[lo], xs[lo + 1]];
+    const span = x1 - x0;
+    if (span === 0)
+        return ys[lo];
+    const tang = tangents ?? monotone_tangents(xs, ys);
+    // d3 monotoneX uses equally-spaced x control points, so x is linear in t. y is the cubic Bezier
+    // through [y0, y0+dx*t0, y1-dx*t1, y1] with dx = span/3.
+    const dx = span / 3;
+    const p0 = ys[lo];
+    const p1 = ys[lo] + dx * tang[lo];
+    const p2 = ys[lo + 1] - dx * tang[lo + 1];
+    const p3 = ys[lo + 1];
+    const frac = (x - x0) / span;
+    const mu = 1 - frac;
+    return (mu * mu * mu * p0 +
+        3 * mu * mu * frac * p1 +
+        3 * mu * frac * frac * p2 +
+        frac * frac * frac * p3);
+}
+// Curve types whose interior follows a (near-)monotone cubic; evaluated via monotone_interpolate.
+// Others (linear/step) evaluate piecewise (exact for them at clip points).
+const MONOTONE_LIKE = new Set([
+    `monotoneX`,
+    `monotoneY`,
+    `natural`,
+    `cardinal`,
+    `catmullRom`,
+    `basis`,
+]);
+// Piecewise (non-cubic) evaluation honoring linear and the three step curves
+const piecewise_eval = (xs, ys, x, curve) => {
+    const edge = endpoint_clamp(xs, ys, x);
+    if (edge !== null)
+        return edge;
+    const idx = bracket(xs, x);
+    const [x0, x1, y0, y1] = [xs[idx], xs[idx + 1], ys[idx], ys[idx + 1]];
+    if (curve === `stepAfter`)
+        return y0; // hold previous until the next knot
+    if (curve === `stepBefore`)
+        return y1; // jump to next value immediately past a knot
+    if (curve === `step`)
+        return x < (x0 + x1) / 2 ? y0 : y1; // switch at the midpoint
+    const span = x1 - x0;
+    return span === 0 ? y0 : y0 + ((x - x0) / span) * (y1 - y0);
+};
+// Build a boundary with a y(x) evaluator that precomputes tangents (monotone) once
+function prepare_boundary(boundary) {
+    const { points, curve } = boundary;
+    const xs = points.map((pt) => pt.x);
+    const ys = points.map((pt) => pt.y);
+    if (MONOTONE_LIKE.has(curve)) {
+        const tangents = monotone_tangents(xs, ys);
+        return { points, curve, eval: (x) => monotone_interpolate(xs, ys, x, tangents) };
+    }
+    return { points, curve, eval: (x) => piecewise_eval(xs, ys, x, curve) };
+}
+// True when a boundary carries its own x (series or data-with-x), so it needs no companion x
+const defines_own_x = (boundary) => typeof boundary !== `number` &&
+    (boundary.type === `series` || (boundary.type === `data` && boundary.x !== undefined));
+// Keep only finite points, sorted by x
+const clean_pts = (pts) => pts.filter((pt) => Number.isFinite(pt.x) && Number.isFinite(pt.y)).sort((a, b) => a.x - b.x);
+// Zip parallel x/y arrays into finite, x-sorted points
+const finite_points = (xs, ys) => clean_pts(Array.from({ length: Math.min(xs.length, ys.length) }, (_, idx) => ({
+    x: xs[idx],
+    y: ys[idx],
+})));
+// Resolve a boundary to native points + curve in data coordinates. `companion` supplies x
+// positions for boundaries that don't define their own (constant/axis/function/data-without-x).
+export function resolve_boundary_points(boundary, series, domains, companion) {
+    // x positions used for companion-relative boundaries
+    const span_xs = companion && companion.length > 0
+        ? companion.map((pt) => pt.x)
+        : [domains.x_domain[0], domains.x_domain[1]];
+    // flat horizontal edge at constant y (number / constant / axis boundaries)
+    const flat_edge = (y) => ({
+        points: horizontal(span_xs, y),
+        curve: `linear`,
+    });
+    // series / function / data edges are traced with monotoneX (matches the series line)
+    const curved_edge = (points) => points.length > 0 ? { points, curve: `monotoneX` } : null;
+    if (typeof boundary === `number`)
+        return flat_edge(boundary);
+    if (boundary.type === `series`) {
+        const resolved = resolve_series_ref(boundary, series);
+        if (!resolved)
+            return null;
+        return curved_edge(finite_points(resolved.x, resolved.y));
+    }
+    if (boundary.type === `constant`)
+        return flat_edge(boundary.value);
+    if (boundary.type === `axis`) {
+        return flat_edge(boundary.value ??
+            (boundary.axis === `y2` ? domains.y2_domain?.[0] : undefined) ??
+            domains.y_domain[0]);
+    }
+    if (boundary.type === `function`) {
+        // sample densely so the traced curve hugs the function
+        const [x0, x1] = [span_xs[0], span_xs[span_xs.length - 1]];
+        const steps = 100;
+        const points = [];
+        for (let idx = 0; idx <= steps; idx++) {
+            const x = x0 + ((x1 - x0) * idx) / steps;
+            const y = boundary.fn(x);
+            if (Number.isFinite(y))
+                points.push({ x, y });
+        }
+        return curved_edge(points);
+    }
+    if (boundary.type === `data`) {
+        if (boundary.values.length === 0)
+            return null;
+        if (boundary.x)
+            return curved_edge(finite_points(boundary.x, boundary.values));
+        // No x: align values to the companion's x by index (or fraction when lengths differ)
+        const num_values = boundary.values.length;
+        const companion_x = (idx) => span_xs.length === num_values
+            ? span_xs[idx]
+            : span_xs[Math.round((idx / Math.max(1, num_values - 1)) * (span_xs.length - 1))];
+        const points = boundary.values.map((value, idx) => ({ x: companion_x(idx), y: value }));
+        return curved_edge(clean_pts(points));
+    }
+    return null;
+}
+// Two points spanning [first, last] of xs at constant y
+const horizontal = (xs, y) => xs.length === 0
+    ? []
+    : [
+        { x: xs[0], y },
+        { x: xs[xs.length - 1], y },
+    ];
+// Clip a prepared boundary to [xa, xb], inserting on-curve endpoints so the edge starts/ends at xa/xb
+function clip_boundary(boundary, xa, xb) {
+    const inside = boundary.points.filter((pt) => pt.x > xa && pt.x < xb);
+    const start = { x: xa, y: boundary.eval(xa) };
+    const end = { x: xb, y: boundary.eval(xb) };
+    const pts = [start, ...inside, end];
+    return pts.filter((pt) => Number.isFinite(pt.y));
+}
+// Binary-search the x where a `where` toggle occurs between two grid samples (boundaries linear between them)
+function where_crossing(xa, xb, ya_up, ya_lo, yb_up, yb_lo, where) {
+    let left = xa;
+    let right = xb;
+    const cond_left = where(xa, ya_up, ya_lo);
+    for (let iter = 0; iter < 24; iter++) {
+        const mid = (left + right) / 2;
+        const frac = (mid - xa) / (xb - xa);
+        const up = ya_up + frac * (yb_up - ya_up);
+        const lo = ya_lo + frac * (yb_lo - ya_lo);
+        if (where(mid, up, lo) === cond_left)
+            left = mid;
+        else
+            right = mid;
+    }
+    return (left + right) / 2;
+}
+// Split the overlap into x-intervals where region.where passes (whole overlap when no condition)
+function where_intervals(upper, lower, xa, xb, where) {
+    if (!where)
+        return [[xa, xb]];
+    // detection grid: native x of both boundaries within the overlap, plus the endpoints
+    const grid = [
+        ...new Set([xa, xb, ...upper.points.map((pt) => pt.x), ...lower.points.map((pt) => pt.x)].filter((x) => x >= xa && x <= xb)),
+    ].sort((a, b) => a - b);
+    const intervals = [];
+    let seg_start = null;
+    // carry the previous grid sample so each point's two evals + where() run once, not twice
+    let prev_x = NaN;
+    let prev_up = NaN;
+    let prev_lo = NaN;
+    let prev_passes = false;
+    for (let idx = 0; idx < grid.length; idx++) {
+        const x = grid[idx];
+        const up = upper.eval(x);
+        const lo = lower.eval(x);
+        const passes = where(x, up, lo);
+        if (idx > 0 && passes !== prev_passes) {
+            const cross = where_crossing(prev_x, x, prev_up, prev_lo, up, lo, where);
+            if (seg_start !== null) {
+                intervals.push([seg_start, cross]);
+                seg_start = null;
+            }
+            else {
+                seg_start = cross;
+            }
+        }
+        if (passes && seg_start === null)
+            seg_start = x;
+        if (!passes && seg_start !== null) {
+            intervals.push([seg_start, x]);
+            seg_start = null;
+        }
+        prev_x = x;
+        prev_up = up;
+        prev_lo = lo;
+        prev_passes = passes;
+    }
+    if (seg_start !== null)
+        intervals.push([seg_start, xb]);
+    return intervals.filter(([a, b]) => b > a);
+}
+// Compute renderable fill segments (data coordinates) for a region.
+// Handles boundary resolution, x-overlap clipping, where-segmentation and y_range clamping.
+export function compute_fill_segments(region, series, domains) {
+    // Resolve self-defining boundaries (series / data-with-x) first; companion-relative ones
+    // (constant/axis/function/data-without-x) then borrow the other's x positions.
+    let upper = defines_own_x(region.upper)
+        ? resolve_boundary_points(region.upper, series, domains)
+        : null;
+    let lower = defines_own_x(region.lower)
+        ? resolve_boundary_points(region.lower, series, domains)
+        : null;
+    upper ??= resolve_boundary_points(region.upper, series, domains, lower?.points);
+    lower ??= resolve_boundary_points(region.lower, series, domains, upper?.points);
+    if (!upper || !lower || upper.points.length === 0 || lower.points.length === 0)
+        return [];
+    // An explicit region.curve overrides the per-boundary curve (advanced: may no longer match the
+    // series line). Default leaves series edges at monotoneX so they coincide with the line.
+    if (region.curve) {
+        upper.curve = region.curve;
+        lower.curve = region.curve;
+    }
+    // Prepare once: precomputes monotone tangents / lookup so the where + clip passes below are
+    // O(grid) instead of recomputing an O(n) evaluator on every sample.
+    const up = prepare_boundary(upper);
+    const lo = prepare_boundary(lower);
+    // x-overlap = intersection of both x-domains, constrained by region.x_range
+    const [x_lo, x_hi] = region.x_range ?? [null, null];
+    const xa = Math.max(up.points[0].x, lo.points[0].x, x_lo ?? -Infinity);
+    const xb = Math.min(up.points[up.points.length - 1].x, lo.points[lo.points.length - 1].x, x_hi ?? Infinity);
+    if (!(xb > xa))
+        return [];
+    const [y_min, y_max] = region.y_range ?? [null, null];
+    const clamp_y = (pt) => ({
+        x: pt.x,
+        y: Math.min(y_max ?? Infinity, Math.max(y_min ?? -Infinity, pt.y)),
+    });
+    const intervals = where_intervals(up, lo, xa, xb, region.where);
+    const segments = [];
+    for (const [sa, sb] of intervals) {
+        const up_pts = clip_boundary(up, sa, sb).map(clamp_y);
+        const lo_pts = clip_boundary(lo, sa, sb).map(clamp_y);
+        if (up_pts.length >= 2 && lo_pts.length >= 2) {
+            segments.push({
+                upper: up_pts,
+                lower: lo_pts,
+                upper_curve: up.curve,
+                lower_curve: lo.curve,
+            });
+        }
+    }
+    return segments;
+}
+// === Path generation ===
+const CURVE_MAP = {
+    linear: curveLinear,
+    monotoneX: curveMonotoneX,
+    monotoneY: curveMonotoneY,
+    step: curveStep,
+    stepBefore: curveStepBefore,
+    stepAfter: curveStepAfter,
+    basis: curveBasis,
+    cardinal: curveCardinal,
+    catmullRom: curveCatmullRom,
+    natural: curveNatural,
+};
+const get_curve = (curve_type) => CURVE_MAP[curve_type] ?? curveMonotoneX;
+const trace = (points, curve_type) => line()
+    .x((pt) => pt.x)
+    .y((pt) => pt.y)
+    .curve(get_curve(curve_type))(points) ?? ``;
+// Generate the closed SVG path for a fill segment (pixel coordinates). The upper edge is traced
+// forward and the lower edge backward, each through its own points with its own curve via the same
+// line generator the series uses, so an unclipped edge matches the corresponding series line.
+export function generate_fill_path(upper, lower, upper_curve = `monotoneX`, lower_curve = upper_curve) {
+    if (upper.length < 2 || lower.length < 2)
+        return ``;
+    const upper_path = trace(upper, upper_curve);
+    const lower_path = trace(lower.toReversed(), lower_curve);
+    if (!upper_path || !lower_path)
+        return ``;
+    // join upper end -> lower end (drop the lower path's leading "M"), then close to upper start
+    return `${upper_path}L${lower_path.slice(1)}Z`;
+}
+// Helper to expand error definition to array
+const expand_error = (err, length) => typeof err === `number` ? Array(length).fill(err) : err;
+// Convert an ErrorBand convenience type to a full FillRegion (carrying the series x so the band
+// traces the central series exactly)
+export function convert_error_band_to_fill_region(error_band, series, default_color) {
+    const resolved = resolve_series_ref(error_band.series, series);
+    if (!resolved)
+        return null;
+    const { x, y } = resolved;
+    const { error } = error_band;
+    const [upper_err, lower_err] = typeof error === `object` && `upper` in error
+        ? [expand_error(error.upper, y.length), expand_error(error.lower, y.length)]
+        : [expand_error(error, y.length), expand_error(error, y.length)];
+    return {
+        id: error_band.id,
+        label: error_band.label,
+        upper: { type: `data`, x, values: y.map((val, idx) => val + upper_err[idx]) },
+        lower: { type: `data`, x, values: y.map((val, idx) => val - lower_err[idx]) },
+        fill: error_band.fill ?? default_color ?? `#4e79a7`,
+        fill_opacity: error_band.fill_opacity ?? 0.3,
+        edge_upper: error_band.edge_style,
+        edge_lower: error_band.edge_style,
+        show_in_legend: error_band.show_in_legend ?? true,
+    };
+}
+// Type guard to check if fill is a gradient
+export const is_fill_gradient = (fill) => typeof fill === `object` && fill !== null && `type` in fill && `stops` in fill;

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

@@ -0,0 +1,10 @@
+export * from './components';
+export * from './data-cleaning';
+export * from './fill-utils';
+export * from './interactions';
+export * from './layout';
+export * from './reference-line';
+export * from './scales';
+export * from './svg';
+export * from './types';
+export * from './utils';

package/dist/plot/core/index.js

@@ -0,0 +1,11 @@
+// Shared cross-chart foundation: types, scales, layout, interactions + primitive components
+export * from './components';
+export * from './data-cleaning';
+export * from './fill-utils';
+export * from './interactions';
+export * from './layout';
+export * from './reference-line';
+export * from './scales';
+export * from './svg';
+export * from './types';
+export * from './utils';

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

@@ -0,0 +1,39 @@
+import { type Point2D, type Vec2 } from '../../math';
+import type { AxisRanges, InitialRanges, ScaleType, Y2SyncConfig, Y2SyncMode } from './types';
+export declare function get_relative_coords(evt: MouseEvent, element?: EventTarget | null): Point2D | null;
+export declare function closest_data_idx(event: Event, attr: string, root?: Element | null): number | null;
+export declare function normalize_y2_sync(sync: Y2SyncConfig | Y2SyncMode | undefined): Y2SyncConfig;
+export declare function sync_y2_range(y1_range: Vec2, y2_base_range: Vec2, sync: Y2SyncConfig): Vec2;
+export declare const snapshot_ranges: ({ x, x2, y, y2 }: AxisRanges) => InitialRanges;
+export declare function pan_range_by_pixels(range: Vec2, pixel_delta: number, pixel_span: number, scale_type?: ScaleType): Vec2;
+export declare function zoom_range_by_factor(range: Vec2, factor: number, scale_type?: ScaleType): Vec2;
+export declare const to_epoch_num: (val: number | Date) => number;
+export declare function remove_drag_listeners(move_handlers: ((evt: MouseEvent) => void)[], up_handlers: ((evt: MouseEvent) => void)[]): void;
+export declare const sorted_range: (a: number, b: number) => Vec2;
+export declare function invert_rect_range(scale: {
+    invert: (px: number) => number | Date;
+}, a_px: number, b_px: number): Vec2 | null;
+export declare const vec2_equal: (a: Vec2, b: Vec2) => boolean;
+export declare const axis_ranges_equal: (a: AxisRanges, b: AxisRanges) => boolean;
+type AxisRangeOverride = {
+    range?: [number | null, number | null];
+};
+type AutoRanges = {
+    x: readonly number[];
+    x2: readonly number[];
+    y: readonly number[];
+    y2: readonly number[];
+};
+export declare function resolve_axis_ranges(axes: {
+    x: AxisRangeOverride;
+    x2: AxisRangeOverride;
+    y: AxisRangeOverride;
+    y2: AxisRangeOverride;
+}, auto: AutoRanges): AxisRanges | null;
+export declare const PINCH_ZOOM_THRESHOLD = 0.1;
+export declare const MIN_TOUCH_DISTANCE_PIXELS = 10;
+export declare function expand_range_if_needed(current: Vec2, new_range: Vec2): {
+    range: Vec2;
+    changed: boolean;
+};
+export {};

package/dist/plot/core/interactions.js

@@ -0,0 +1,209 @@
+import { LOG_EPS } from '../../math';
+import { get_arcsinh_threshold, get_scale_type_name } from './types';
+// Get coordinates of a mouse event relative to an element (the event's
+// currentTarget by default; pass `element` when the handler is delegated and the
+// reference frame differs, e.g. coordinates relative to the svg root)
+export function get_relative_coords(evt, element = evt.currentTarget) {
+    if (!(element instanceof Element))
+        return null;
+    const box = element.getBoundingClientRect();
+    if (!box)
+        return null;
+    return { x: evt.clientX - box.left, y: evt.clientY - box.top };
+}
+// Resolve a delegated event to the integer value of the nearest ancestor's data
+// attribute (e.g. data-sunburst-node-idx), scoped to `root` so targets outside the
+// component don't leak in. Returns null when the event didn't hit an indexed element.
+export function closest_data_idx(event, attr, root) {
+    const target = event.target instanceof Element ? event.target.closest(`[${attr}]`) : null;
+    if (!target || (root && !root.contains(target)))
+        return null;
+    const idx = Number(target.getAttribute(attr));
+    return Number.isInteger(idx) ? idx : null;
+}
+// Normalize Y2 sync config (handle shorthand string vs full object)
+export function normalize_y2_sync(sync) {
+    if (!sync || sync === `none`)
+        return { mode: `none` };
+    if (typeof sync === `string`)
+        return { mode: sync };
+    return sync;
+}
+// Helper to check if all values in ranges are finite
+const all_finite = (...ranges) => ranges.every(([a, b]) => Number.isFinite(a) && Number.isFinite(b));
+// Calculate synced y2 range based on sync mode
+export function sync_y2_range(y1_range, y2_base_range, sync) {
+    if (sync.mode === `none`)
+        return y2_base_range;
+    if (!all_finite(y1_range, y2_base_range))
+        return y2_base_range;
+    // Synced: Y2 has exact same range as Y1
+    if (sync.mode === `synced`) {
+        return [y1_range[0], y1_range[1]];
+    }
+    // Align: Position so align_val (default 0) is at same relative position on both axes
+    // Y2 range expands as needed to show all data while maintaining alignment
+    if (sync.mode === `align`) {
+        const align_val = sync.align_value ?? 0;
+        const y1_span = y1_range[1] - y1_range[0];
+        if (y1_span === 0)
+            return y2_base_range;
+        // Where is align_val in Y1's range? (0 = bottom, 1 = top)
+        const rel_pos = (align_val - y1_range[0]) / y1_span;
+        // Ensure Y2 range includes both align_val and all data
+        const y2_min_data = Math.min(y2_base_range[0], align_val);
+        const y2_max_data = Math.max(y2_base_range[1], align_val);
+        // Calculate minimum span needed to fit all data while keeping align_val at rel_pos
+        // Constraints: y2_min <= y2_min_data AND y2_max >= y2_max_data
+        let y2_span = y2_max_data - y2_min_data;
+        if (rel_pos > 0) {
+            y2_span = Math.max(y2_span, (align_val - y2_min_data) / rel_pos);
+        }
+        if (rel_pos < 1) {
+            y2_span = Math.max(y2_span, (y2_max_data - align_val) / (1 - rel_pos));
+        }
+        const y2_min_computed = align_val - rel_pos * y2_span;
+        const y2_max_computed = align_val + (1 - rel_pos) * y2_span;
+        // When align_val is outside y1_range (rel_pos < 0 or > 1), the formula can produce
+        // a range that omits y2_base_range or align_val. Ensure both are always included.
+        const y2_min = Math.min(y2_min_computed, y2_base_range[0], align_val);
+        const y2_max = Math.max(y2_max_computed, y2_base_range[1], align_val);
+        return [y2_min, y2_max];
+    }
+    return y2_base_range;
+}
+// Forward/inverse transform pair mapping an axis's data values onto its visual
+// metric (the space where equal pixel steps are equal steps; identity for
+// linear/time). Pan and pinch must be uniform in *screen* space - doing the math
+// linearly on a log axis stretches one end of the view and shifts past zero into
+// an all-NaN domain. log clamps at LOG_EPS so a non-positive bound (stale explicit
+// range) recovers instead of propagating -Infinity.
+function axis_transform(scale_type) {
+    const name = get_scale_type_name(scale_type);
+    if (name === `log`) {
+        return { to: (val) => Math.log(Math.max(val, LOG_EPS)), from: Math.exp };
+    }
+    if (name === `arcsinh`) {
+        const threshold = get_arcsinh_threshold(scale_type);
+        const to = (val) => Math.asinh(val / threshold);
+        const from = (val) => Math.sinh(val) * threshold;
+        return { to, from };
+    }
+    return { to: (val) => val, from: (val) => val };
+}
+// Snapshot the four axis ranges as fresh tuples at pan/zoom/touch interaction start
+export const snapshot_ranges = ({ x, x2, y, y2 }) => ({
+    initial_x_range: [...x],
+    initial_x2_range: [...x2],
+    initial_y_range: [...y],
+    initial_y2_range: [...y2],
+});
+// Pan a range by a pixel delta, uniformly in screen space: linear axes shift by a
+// constant amount, log axes by a constant factor (which also can't cross zero).
+// `pixel_span` is the plot's pixel extent along the axis.
+export function pan_range_by_pixels(range, pixel_delta, pixel_span, scale_type) {
+    if (pixel_span === 0)
+        return range;
+    const { to, from } = axis_transform(scale_type);
+    const [t0, t1] = [to(range[0]), to(range[1])];
+    const t_delta = (pixel_delta / pixel_span) * (t1 - t0);
+    return [from(t0 + t_delta), from(t1 + t_delta)];
+}
+// Zoom a range about its screen-space center by `factor` (pinch: >1 zooms in).
+// On log axes the fixed point is the geometric mean - the visual center.
+export function zoom_range_by_factor(range, factor, scale_type) {
+    // Guard invalid factors (0/negative/NaN) that would emit Infinity/NaN into axis state
+    if (!Number.isFinite(factor) || factor <= 0)
+        return range;
+    const { to, from } = axis_transform(scale_type);
+    const [t0, t1] = [to(range[0]), to(range[1])];
+    const center = (t0 + t1) / 2;
+    const half_span = (t1 - t0) / factor / 2;
+    return [from(center - half_span), from(center + half_span)];
+}
+// Coerce a scale.invert result (number, or Date for time scales) to an epoch number
+export const to_epoch_num = (val) => val instanceof Date ? val.getTime() : val;
+// Remove window drag/pan listeners and reset the body cursor. Call from onDestroy:
+// a component unmounting mid-drag would otherwise leak its listeners and leave the
+// cursor stuck (the mouseup that normally cleans up never fires after unmount).
+export function remove_drag_listeners(move_handlers, up_handlers) {
+    if (typeof window === `undefined`)
+        return;
+    for (const handler of move_handlers) {
+        window.removeEventListener(`mousemove`, handler);
+    }
+    for (const handler of up_handlers) {
+        window.removeEventListener(`mouseup`, handler);
+    }
+    document.body.style.cursor = ``;
+}
+// Sorted [min, max] from two scalar bounds (rect-zoom inverts drag start/end,
+// which arrive in either order depending on drag direction)
+export const sorted_range = (a, b) => [Math.min(a, b), Math.max(a, b)];
+// Invert a drag-rect edge pair through a scale to a sorted finite data range
+// (time scales invert to Dates, coerced to epoch numbers). Returns null when
+// either bound is non-finite or the range is degenerate (zero span).
+export function invert_rect_range(scale, a_px, b_px) {
+    const range = sorted_range(to_epoch_num(scale.invert(a_px)), to_epoch_num(scale.invert(b_px)));
+    return range.every(Number.isFinite) && range[0] !== range[1] ? range : null;
+}
+// Strict per-bound equality of two [min, max] ranges
+export const vec2_equal = (a, b) => a[0] === b[0] && a[1] === b[1];
+// True when all four axis ranges match. The range-sync effects use this to skip
+// no-op writes that would otherwise re-trigger the effect and loop.
+export const axis_ranges_equal = (a, b) => vec2_equal(a.x, b.x) &&
+    vec2_equal(a.x2, b.x2) &&
+    vec2_equal(a.y, b.y) &&
+    vec2_equal(a.y2, b.y2);
+// Merge each axis's explicit range over its auto range (per-bound: a null bound
+// falls back to the auto value). Returns null if any resolved bound is non-finite so
+// the caller can skip the sync - writing NaN breaks scales and, since NaN !== NaN,
+// makes the change comparison never settle (an infinite effect loop).
+export function resolve_axis_ranges(axes, auto) {
+    const resolve = (axis, fallback) => [
+        axis.range?.[0] ?? fallback[0],
+        axis.range?.[1] ?? fallback[1],
+    ];
+    const next = {
+        x: resolve(axes.x, auto.x),
+        x2: resolve(axes.x2, auto.x2),
+        y: resolve(axes.y, auto.y),
+        y2: resolve(axes.y2, auto.y2),
+    };
+    for (const [lo, hi] of [next.x, next.x2, next.y, next.y2]) {
+        if (!Number.isFinite(lo) || !Number.isFinite(hi))
+            return null;
+    }
+    return next;
+}
+// Threshold for distinguishing pinch-zoom from pan in touch gestures
+// Scale change > this value triggers zoom instead of pan
+export const PINCH_ZOOM_THRESHOLD = 0.1;
+// Minimum start distance (px) between two touches to treat the gesture as a valid pinch.
+// Guards curr_dist / start_dist scale from blowing up on near-coincident touches
+export const MIN_TOUCH_DISTANCE_PIXELS = 10;
+// Helper to check if range is the default [0, 1] sentinel (no data)
+// Note: min === 0 handles -0 correctly since -0 === 0 in JavaScript
+const is_default_range = ([min, max]) => min === 0 && max === 1;
+// Adopt the new data range, unless all series were hidden (sentinel [0, 1] fallback).
+// NOTE: [0, 1] is the "no data" sentinel - when all series are hidden, auto ranges
+// fall back to [0, 1]. Actual data spanning exactly [0, 1] is a rare edge case.
+export function expand_range_if_needed(current, new_range) {
+    // Guard against NaN/Infinity - prefer valid range, fall back to sentinel [0, 1] if both invalid
+    const current_valid = all_finite(current);
+    const new_valid = all_finite(new_range);
+    if (!current_valid && !new_valid)
+        return { range: [0, 1], changed: true };
+    if (!new_valid)
+        return { range: current, changed: false };
+    if (!current_valid)
+        return { range: new_range, changed: true };
+    // When all series are hidden, auto ranges fall back to [0, 1] sentinel.
+    // Don't shrink to that — preserve the current view so it doesn't jump.
+    if (!is_default_range(current) && is_default_range(new_range)) {
+        return { range: current, changed: false };
+    }
+    // Otherwise adopt the new range directly (both expand and shrink)
+    const changed = new_range[0] !== current[0] || new_range[1] !== current[1];
+    return { range: new_range, changed };
+}

package/dist/plot/{layout.d.ts → core/layout.d.ts}

@@ -6,6 +6,7 @@ export type Sides = {
     r?: number;
 };
 export declare const LABEL_GAP_DEFAULT = 30;
+export declare function y2_axis_label_x(axis: AxisConfig, width: number, pad_r: number, max_tick_width: number): number;
 export declare const filter_padding: (padding: Partial<Sides> | undefined | null, defaults: Required<Sides>) => Required<Sides>;
 export declare function measure_text_width(text: string, font?: string): number;
 export declare function measure_full_footprint(el: HTMLElement): {