matterviz 0.4.0 → 0.4.2

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

@@ -1,8 +1,9 @@
 // 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.
+// uses (a series edge inherits the series' `line_style.curve`, default monotoneX), so an unclipped
+// fill edge coincides with the line it borders. When an edge is clipped (x_range / partial
+// overlap), inserted endpoints are evaluated on a monotone-cubic approximation: sub-pixel for
+// monotoneX/linear/step, but natural/basis/catmullRom edges can deviate more at the clip points.
 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;
@@ -91,9 +92,12 @@ export function monotone_interpolate(xs, ys, x, tangents) {
     const p1 = ys[lo] + dx * tang[lo];
     const p2 = ys[lo + 1] - dx * tang[lo + 1];
     const p3 = ys[lo + 1];
-    const u = (x - x0) / span;
-    const mu = 1 - u;
-    return mu * mu * mu * p0 + 3 * mu * mu * u * p1 + 3 * mu * u * u * p2 + u * u * u * p3;
+    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).
@@ -142,6 +146,19 @@ const finite_points = (xs, ys) => clean_pts(Array.from({ length: Math.min(xs.len
     x: xs[idx],
     y: ys[idx],
 })));
+// Bridge the public LineCurve vocabulary (series `line_style.curve`) to FillCurveType names so
+// a series fill edge traces with the same curve as its rendered line. Default: monotoneX.
+const LINE_CURVE_TO_FILL = {
+    linear: `linear`,
+    monotone: `monotoneX`,
+    natural: `natural`,
+    step: `step`,
+    basis: `basis`,
+    'catmull-rom': `catmullRom`,
+};
+const line_curve_to_fill = (curve) => 
+// ?? monotoneX guards an unknown string from an untyped (Python/JSON) caller
+(curve ? LINE_CURVE_TO_FILL[curve] : undefined) ?? `monotoneX`;
 // 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) {
@@ -154,15 +171,16 @@ export function resolve_boundary_points(boundary, series, domains, companion) {
         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;
+    // function / data edges trace with monotoneX by default; a series edge inherits the
+    // series' own line curve so the fill border coincides with the rendered line
+    const curved_edge = (points, curve = `monotoneX`) => (points.length > 0 ? { points, curve } : 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));
+        return curved_edge(finite_points(resolved.x, resolved.y), line_curve_to_fill(resolved.line_style?.curve));
     }
     if (boundary.type === `constant`)
         return flat_edge(boundary.value);
@@ -342,6 +360,10 @@ const CURVE_MAP = {
     natural: curveNatural,
 };
 const get_curve = (curve_type) => CURVE_MAP[curve_type] ?? curveMonotoneX;
+// Resolve a public LineCurve (a series' `line_style.curve`) to its d3 CurveFactory. Single source
+// of truth shared by Line.svelte and PlotMarginals.svelte (composes the LineCurve -> FillCurveType
+// -> CurveFactory maps); unknown/undefined falls back to curveMonotoneX.
+export const line_curve_factory = (curve) => get_curve(line_curve_to_fill(curve));
 const trace = (points, curve_type) => line()
     .x((pt) => pt.x)
     .y((pt) => pt.y)
@@ -375,6 +397,9 @@ export function convert_error_band_to_fill_region(error_band, series, default_co
     return {
         id: error_band.id,
         label: error_band.label,
+        // band edges are data boundaries (default monotoneX); inherit the central series' line
+        // curve so the band traces with the same curve as the line it brackets
+        curve: line_curve_to_fill(resolved.line_style?.curve),
         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`,

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

@@ -3,6 +3,7 @@ export * from './data-cleaning';
 export * from './fill-utils';
 export * from './interactions';
 export * from './layout';
+export * from './marginals';
 export * from './reference-line';
 export * from './scales';
 export * from './svg';

package/dist/plot/core/index.js

@@ -4,6 +4,7 @@ export * from './data-cleaning';
 export * from './fill-utils';
 export * from './interactions';
 export * from './layout';
+export * from './marginals';
 export * from './reference-line';
 export * from './scales';
 export * from './svg';

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

@@ -1,14 +1,18 @@
 import { type Point2D, type Vec2 } from '../../math';
-import type { AxisRanges, ScaleType, Y2SyncConfig, Y2SyncMode } from './types';
+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 = {

package/dist/plot/core/interactions.js

@@ -7,8 +7,6 @@ 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
@@ -91,6 +89,13 @@ function axis_transform(scale_type) {
     }
     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.
@@ -133,6 +138,13 @@ export function remove_drag_listeners(move_handlers, up_handlers) {
 // 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

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

@@ -5,7 +5,8 @@ export type Sides = {
     l?: number;
     r?: number;
 };
-export declare const LABEL_GAP_DEFAULT = 30;
+export declare const LABEL_GAP_DEFAULT = 20;
+export declare const DEFAULT_PLOT_PADDING: Required<Sides>;
 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;
@@ -30,6 +31,7 @@ export interface AutoPaddingConfig {
 export declare const measure_max_tick_width: (ticks: (string | number)[], format?: string) => number;
 export declare const TICK_LABEL_HEIGHT = 16;
 export declare const AXIS_LABEL_HEIGHT = 20;
+export declare const AXIS_TITLE_OFFSET: number;
 export declare const calc_auto_padding: ({ padding, default_padding, x2_axis, y_axis, y2_axis, label_gap, }: AutoPaddingConfig) => Required<Sides>;
 export declare function constrain_tooltip_position(cursor_x: number, cursor_y: number, tooltip_width: number, tooltip_height: number, viewport_width: number, viewport_height: number, options?: {
     offset?: number;

package/dist/plot/core/layout.js

@@ -1,7 +1,10 @@
 import { format_value } from '../../labels';
 import { euclidean_dist } from '../../math';
 // Default gap between tick labels and axis labels
-export const LABEL_GAP_DEFAULT = 30;
+export const LABEL_GAP_DEFAULT = 20;
+// Default plot padding (px) reserved for axis ticks/labels, shared by
+// Histogram/BarPlot/BoxPlot/BinnedScatterPlot (ScatterPlot keeps its own bespoke default)
+export const DEFAULT_PLOT_PADDING = { t: 20, b: 60, l: 60, r: 20 };
 // X position for a right-side (y2) axis label: past the plot edge plus tick shift and
 // measured tick-label width (both zero when tick labels render inside the plot)
 export function y2_axis_label_x(axis, width, pad_r, max_tick_width) {
@@ -56,22 +59,28 @@ export const measure_max_tick_width = (ticks, format = ``) => ticks.length === 0
 export const TICK_LABEL_HEIGHT = 16;
 // Estimated height of an axis label (font-size ~14px + margin)
 export const AXIS_LABEL_HEIGHT = 20;
+// Distance from an x/x2 axis baseline to the title center.
+export const AXIS_TITLE_OFFSET = TICK_LABEL_HEIGHT + LABEL_GAP_DEFAULT;
 export const calc_auto_padding = ({ padding, default_padding, x2_axis = {}, y_axis = {}, y2_axis = {}, label_gap = LABEL_GAP_DEFAULT, }) => {
-    const x2_ticks = x2_axis.tick_values ?? [];
-    const y_ticks = y_axis.tick_values ?? [];
-    const y_format = y_axis.format ?? ``;
-    const y2_ticks = y2_axis.tick_values ?? [];
-    const y2_format = y2_axis.format ?? ``;
+    // Padding for a vertical-axis side (y/y2): when ticks render, reserve widest tick label + gap +
+    // the rotated axis-title width (mirrors the `t` branch's AXIS_LABEL_HEIGHT) so a wide tick label
+    // can't overlap the title. With no tick labels (e.g. no y2 series) reserve nothing extra.
+    const side_pad = (axis, default_side) => {
+        const ticks = axis.tick_values ?? [];
+        if (ticks.length === 0)
+            return default_side;
+        return Math.max(default_side, measure_max_tick_width(ticks, axis.format ?? ``) +
+            label_gap +
+            (axis.label ? AXIS_LABEL_HEIGHT : 0));
+    };
     return {
         t: padding.t ??
-            (x2_ticks.length > 0
+            ((x2_axis.tick_values ?? []).length > 0
                 ? Math.max(default_padding.t, TICK_LABEL_HEIGHT + label_gap + (x2_axis.label ? AXIS_LABEL_HEIGHT : 0))
                 : default_padding.t),
         b: padding.b ?? default_padding.b,
-        l: padding.l ??
-            Math.max(default_padding.l, measure_max_tick_width(y_ticks, y_format) + label_gap),
-        r: padding.r ??
-            Math.max(default_padding.r, measure_max_tick_width(y2_ticks, y2_format) + label_gap),
+        l: padding.l ?? side_pad(y_axis, default_padding.l),
+        r: padding.r ?? side_pad(y2_axis, default_padding.r),
     };
 };
 // Constrain tooltip position within bounds, flipping to opposite side if overflow
@@ -216,9 +225,9 @@ export function compute_element_placement(config) {
         ? (effective_y_max - effective_y_min) / (grid_resolution - 1)
         : 0;
     // Precompute plot corners (constant across all candidates)
-    const plot_left = plot_bounds.x + axis_clearance;
+    const plot_left = valid_x_min;
     const plot_right = plot_bounds.x + plot_bounds.width - axis_clearance;
-    const plot_top = plot_bounds.y + axis_clearance;
+    const plot_top = valid_y_min;
     const plot_bottom = plot_bounds.y + plot_bounds.height - axis_clearance;
     const max_corner_dist = euclidean_dist([plot_left, plot_top], [plot_right, plot_bottom]);
     for (let grid_x = 0; grid_x < grid_resolution; grid_x++) {

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

@@ -0,0 +1,170 @@
+import type { Vec2 } from '../../math';
+import type { Rect, Sides } from './layout';
+import type { LineCurve, ScaleType } from './types';
+import type { Snippet } from 'svelte';
+export type MarginalSide = `top` | `bottom` | `left` | `right`;
+export type MarginalType = `histogram` | `kde` | `cdf` | `rug`;
+export type MarginalPlacement = `auto` | `flush` | `outer`;
+export type MarginalNormalize = `count` | `density` | `probability`;
+export type MarginalAxisBinding = `x1` | `x2` | `y1` | `y2`;
+export declare const MARGINAL_SIDES: readonly ["top", "bottom", "left", "right"];
+export type MarginalCurve = {
+    kind: `bars`;
+    bins: {
+        pos0: number;
+        pos1: number;
+        value: number;
+    }[];
+    max: number;
+} | {
+    kind: `line`;
+    points: {
+        pos: number;
+        value: number;
+    }[];
+    max: number;
+} | {
+    kind: `rug`;
+    positions: number[];
+};
+export interface MarginalComputeContext {
+    config: ResolvedMarginalConfig;
+    side: MarginalSide;
+    positional_range: Vec2;
+    scale_type: ScaleType;
+}
+export interface MarginalConfig {
+    type?: MarginalType;
+    size?: number;
+    gap?: number;
+    placement?: MarginalPlacement;
+    axis?: MarginalAxisBinding;
+    bins?: number;
+    bandwidth?: number | `silverman` | `scott`;
+    normalize?: MarginalNormalize;
+    per_series?: boolean;
+    color?: string;
+    fill?: string;
+    fill_opacity?: number;
+    stroke?: string;
+    stroke_width?: number;
+    opacity?: number;
+    curve?: LineCurve;
+    value_range?: Vec2;
+    value_axis?: boolean;
+    label?: string;
+    data?: readonly number[] | ((ctx: MarginalComputeContext) => readonly number[]);
+    reduce?: (values: number[], weights: number[] | undefined, ctx: MarginalComputeContext) => MarginalCurve;
+    snippet?: Snippet<[MarginalRenderContext]>;
+    hover?: boolean;
+    tooltip?: Snippet<[MarginalHover]>;
+    class?: string;
+    style?: string;
+}
+export type ResolvedMarginalConfig = MarginalConfig & {
+    type: MarginalType;
+    size: number;
+    gap: number;
+    placement: MarginalPlacement;
+    per_series: boolean;
+    bins: number;
+    bandwidth: number | `silverman` | `scott`;
+    stroke_width: number;
+    opacity: number;
+    value_axis: boolean;
+};
+export type MarginalSideInput = boolean | MarginalType | MarginalConfig;
+export type MarginalsProp = boolean | MarginalType | Partial<Record<MarginalSide, MarginalSideInput>>;
+export type ResolvedMarginals = Record<MarginalSide, ResolvedMarginalConfig | null>;
+export interface MarginalSeriesInput {
+    x?: ArrayLike<number>;
+    y?: ArrayLike<number>;
+    weight?: ArrayLike<number>;
+    color: string;
+    label?: string;
+    visible?: boolean;
+    x_axis?: `x1` | `x2`;
+    y_axis?: `y1` | `y2`;
+}
+export interface MarginalSeriesCurve {
+    series_idx: number;
+    color: string;
+    label?: string;
+    curve: MarginalCurve;
+}
+export type ScaleFn = (value: number) => number;
+export interface MarginalAxis {
+    scale: ScaleFn;
+    range: Vec2;
+    scale_type?: ScaleType;
+    format?: string;
+    tick_label?: (value: number) => string | undefined;
+    label?: string;
+}
+export type MarginalAxes = {
+    x1: MarginalAxis;
+    x2?: MarginalAxis;
+    y1: MarginalAxis;
+    y2?: MarginalAxis;
+};
+export declare const marginal_axis: (scale: ScaleFn, range: Vec2, axis: {
+    scale_type?: ScaleType;
+    format?: string;
+    label?: string;
+}, tick_label?: (value: number) => string | undefined) => MarginalAxis;
+export interface MarginalRenderContext extends MarginalComputeContext {
+    rect: Rect;
+    positional_scale: ScaleFn;
+    value_scale: ScaleFn;
+    baseline: number;
+    curves: MarginalSeriesCurve[];
+    series: MarginalSeriesInput[];
+    format?: string;
+    tick_label?: (value: number) => string | undefined;
+    axis_title?: string;
+}
+export declare const MARGINAL_HIT_TOLERANCE_PX = 10;
+export interface MarginalHover {
+    side: MarginalSide;
+    x: number;
+    y: number;
+    color: string;
+    label?: string;
+    kind: MarginalCurve[`kind`];
+    pos: number;
+    pos0?: number;
+    pos1?: number;
+    value?: number;
+    config: ResolvedMarginalConfig;
+    scale_type: ScaleType;
+    format?: string;
+    pos_label?: string;
+    axis_title?: string;
+}
+export declare function marginal_hit(ctx: MarginalRenderContext, px: number, py: number): MarginalHover | null;
+export declare const MARGINAL_DEFAULTS: {
+    type: MarginalType;
+    size: number;
+    gap: number;
+    placement: MarginalPlacement;
+    per_series: boolean;
+    bins: number;
+    bandwidth: "silverman";
+    stroke_width: number;
+    opacity: number;
+    value_axis: boolean;
+};
+export declare function normalize_marginals(prop: MarginalsProp | undefined, default_sides?: Partial<Record<MarginalSide, MarginalSideInput>>): ResolvedMarginals;
+export declare function reserve_marginal_pad(resolved: ResolvedMarginals): Required<Sides>;
+export declare const add_sides: (a: Required<Sides>, b: Required<Sides>) => Required<Sides>;
+export declare const default_axis_for_side: (side: MarginalSide) => MarginalAxisBinding;
+export declare const marginal_axis_presence: (top: boolean, right: boolean) => Record<MarginalSide, boolean>;
+export declare function marginal_strip_rect(side: MarginalSide, pad: Required<Sides>, width: number, height: number, config: ResolvedMarginalConfig, has_axis: boolean): Rect;
+export declare function marginal_value_scale(side: MarginalSide, rect: Rect, domain: Vec2): {
+    scale: (value: number) => number;
+    baseline: number;
+};
+export declare function compute_marginal_curve(positions: ArrayLike<number>, weights: ArrayLike<number> | undefined, config: ResolvedMarginalConfig, positional_range: Vec2, scale_type: ScaleType): MarginalCurve;
+export declare const curves_max: (curves: MarginalCurve[]) => number;
+export declare const default_marginal_label: (config: ResolvedMarginalConfig) => string;
+export declare const marginal_value_format: (config: ResolvedMarginalConfig) => string;