matterviz 0.4.1 → 0.4.3

package/dist/plot/core/placed-tween.svelte.js

@@ -5,9 +5,9 @@ import { Tween } from 'svelte/motion';
 const HOVER_DEBOUNCE_MS = 300;
 // Tweened position for an auto-placed plot element with the stability gating shared
 // by BarPlot/BoxPlot/Histogram/ScatterPlot legends: snap (no animation) on first
-// placement, follow container resizes, stay put while hovered (debounced hover lock),
-// and track placement continuously only when `responsive`. Creates $effects, so it
-// must be called during component init.
+// placement, follow container/element resizes, stay put while hovered (debounced
+// hover lock), and track placement continuously only when `responsive`. Creates
+// $effects, so it must be called during component init.
 export function create_placed_tween(opts) {
     // Hover lock: placement updates pause while the element is hovered; release is
     // debounced so brief mouse-outs don't cause jumps
@@ -22,16 +22,43 @@ export function create_placed_tween(opts) {
         else
             unlock_timeout = setTimeout(() => (hover_locked = false), HOVER_DEBOUNCE_MS);
     };
-    // Plain (untracked) flags: only read/written inside the effect below, and outcomes
-    // don't depend on re-running when they flip
+    // Previous plot dimensions stay plain; they only classify the current effect run.
     let prev_dims = null;
-    let has_initial_placement = false;
+    let element_size_revision = $state(0);
+    let prev_element_size_revision = 0;
+    let previous_element;
+    let previous_placement_revision;
+    let placed = $state(false);
     const coords = new Tween({ x: 0, y: 0 }, untrack(() => ({ duration: 400, ...opts.tween?.() })));
     // Clear pending unlock timeout to prevent state updates after unmount
     $effect(() => () => {
         if (unlock_timeout)
             clearTimeout(unlock_timeout);
     });
+    // Decoration content (title, orientation, tick labels) can resize without the
+    // plot dimensions changing. Observe it so frozen placements are recomputed.
+    $effect(() => {
+        const element = opts.element() ?? null;
+        if (previous_element !== undefined && previous_element !== element) {
+            element_size_revision += 1;
+            if (!element)
+                placed = false;
+        }
+        previous_element = element;
+        if (!element || typeof ResizeObserver === `undefined`)
+            return undefined;
+        const observed_elements = new WeakSet();
+        const observer = new ResizeObserver((entries) => {
+            const size_changed = entries.some(({ target }) => observed_elements.has(target));
+            for (const { target } of entries)
+                observed_elements.add(target);
+            if (size_changed)
+                element_size_revision += 1;
+        });
+        for (const target of [element, ...element.querySelectorAll(`*`)])
+            observer.observe(target);
+        return () => observer.disconnect();
+    });
     // Update position with stability checks
     $effect(() => {
         const { width, height } = opts.dims();
@@ -43,26 +70,46 @@ export function create_placed_tween(opts) {
         if (manual) {
             // Immediate update (no animation) for manually positioned elements
             void coords.set({ x: manual.x, y: manual.y }, { duration: 0 });
-            return;
+            if (opts.element())
+                placed = true;
         }
-        const placement = opts.placement();
-        if (!placement)
+        // Leave resize revisions pending so unlock recomputes the latest placement.
+        if (hover_locked)
             return;
         // Track dimensions for resize detection
         const dims_changed = !prev_dims || prev_dims.width !== width || prev_dims.height !== height;
         if (dims_changed)
             prev_dims = { width, height };
-        // Only update if: resize occurred, OR (not hover-locked AND (responsive OR not
-        // yet initially placed))
-        const should_update = dims_changed || (!hover_locked && (opts.responsive() || !has_initial_placement));
-        if (should_update) {
-            void coords.set({ x: placement.x, y: placement.y }, 
-            // Skip animation on initial placement to avoid jump from (0, 0)
-            has_initial_placement ? undefined : { duration: 0 });
-            // Only lock position after the element has an actual measured size
-            if (opts.element())
-                has_initial_placement = true;
-        }
+        const element_size_changed = prev_element_size_revision !== element_size_revision;
+        prev_element_size_revision = element_size_revision;
+        if (element_size_changed)
+            opts.on_element_resize?.();
+        if (manual)
+            return;
+        const placement_revision = opts.placement_revision?.();
+        const placement_invalidated = !Object.is(previous_placement_revision, placement_revision);
+        previous_placement_revision = placement_revision;
+        const responsive = opts.responsive();
+        // A non-responsive tween tracks `placed` once so it immediately reruns and
+        // unsubscribes from the expensive placement chain after its first placement.
+        const has_initial_placement = responsive ? untrack(() => placed) : placed;
+        // Skip expensive DOM placement before evaluating it: non-responsive
+        // elements stay fixed after their initial placement until the plot resizes.
+        if (!dims_changed &&
+            !element_size_changed &&
+            !placement_invalidated &&
+            !responsive &&
+            has_initial_placement)
+            return;
+        const placement = opts.placement();
+        if (!placement)
+            return;
+        void coords.set({ x: placement.x, y: placement.y }, 
+        // Skip animation on initial placement to avoid jump from (0, 0)
+        has_initial_placement ? undefined : { duration: 0 });
+        // Only lock position after the element has an actual measured size
+        if (opts.element())
+            placed = true;
     });
-    return { coords, set_locked };
+    return { coords, placed: () => placed, set_locked };
 }

package/dist/plot/core/reference-line.js

@@ -210,7 +210,7 @@ export function calculate_annotation_position(x1, y1, x2, y2, annotation) {
     // Calculate base position with edge padding applied along line direction
     const dx = x2 - x1;
     const dy = y2 - y1;
-    const len = Math.sqrt(dx * dx + dy * dy);
+    const len = Math.hypot(dx, dy);
     let base_x = x1 + frac * dx;
     let base_y = y1 + frac * dy;
     // Apply edge padding to pull text slightly inward from plot boundaries

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

@@ -17,6 +17,29 @@ export type PlotScaleFn = ScaleContinuousNumeric<number, number> | ScaleTime<num
 export declare function scale_arcsinh(threshold?: number): ArcsinhScale;
 export declare function generate_arcsinh_ticks(min: number, max: number, threshold?: number, count?: number): number[];
 export declare function create_scale(scale_type: ScaleType, domain: Vec2, output_range: Vec2): ScaleContinuousNumeric<number, number> | ArcsinhScale;
+export declare function create_axis_scales<A extends {
+    scale_type?: ScaleType;
+}>(axes: {
+    x: A;
+    x2: A;
+    y: A;
+    y2: A;
+}, ranges: {
+    x: Vec2;
+    x2: Vec2;
+    y: Vec2;
+    y2: Vec2;
+}, pad: {
+    l: number;
+    r: number;
+    t: number;
+    b: number;
+}, width: number, height: number): {
+    x: ArcsinhScale | ScaleContinuousNumeric<number, number, never>;
+    x2: ArcsinhScale | ScaleContinuousNumeric<number, number, never>;
+    y: ArcsinhScale | ScaleContinuousNumeric<number, number, never>;
+    y2: ArcsinhScale | ScaleContinuousNumeric<number, number, never>;
+};
 export declare const create_time_scale: (domain: Vec2, output_range: Vec2) => ScaleTime<number, number, never>;
 export declare function generate_ticks(domain: Vec2, scale_type: ScaleType, ticks_option: TicksOption | undefined, scale_fn: PlotScaleFn, // D3 scale function with .ticks() method
 options?: {

package/dist/plot/core/scales.js

@@ -1,5 +1,7 @@
 import * as math from '../../math';
-import { get_arcsinh_threshold, get_scale_type_name, is_time_scale, } from './types';
+import { get_d3_interpolator } from '../../colors';
+import { clamp01 } from '../../utils';
+import { get_arcsinh_threshold, get_scale_type_name, is_time_scale, SCALE_DEFAULTS, } from './types';
 import { extent, range } from 'd3-array';
 import { scaleLinear, scaleLog, scaleSequential, scaleSequentialLog, scaleTime, } from 'd3-scale';
 import * as d3_sc from 'd3-scale-chromatic';
@@ -188,6 +190,19 @@ export function create_scale(scale_type, domain, output_range) {
     // For 'time' or 'linear', return linear scale (time scales need create_time_scale())
     return scaleLinear().domain(domain).range(output_range);
 }
+// Build the four axis scales for a 2D plot in one call: x/x2 share the horizontal pixel span,
+// y/y2 the inverted vertical one. Shared by BarPlot/BoxPlot/Histogram (identical layout math).
+export function create_axis_scales(axes, ranges, pad, width, height) {
+    const x_px = [pad.l, width - pad.r];
+    const y_px = [height - pad.b, pad.t];
+    const scale = (axis, domain, px) => create_scale(axis.scale_type ?? `linear`, domain, px);
+    return {
+        x: scale(axes.x, ranges.x, x_px),
+        x2: scale(axes.x2, ranges.x2, x_px),
+        y: scale(axes.y, ranges.y, y_px),
+        y2: scale(axes.y2, ranges.y2, y_px),
+    };
+}
 // Create a time scale for time-based data
 export const create_time_scale = (domain, output_range) => scaleTime()
     .domain([new Date(domain[0]), new Date(domain[1])])
@@ -263,9 +278,13 @@ export function calculate_domain(values, scale_type = `linear`) {
     if (min_val === undefined || max_val === undefined)
         return [0, 1];
     const type_name = get_scale_type_name(scale_type);
-    // Only log scale needs domain clamping to positive values
-    // Arcsinh and linear can handle any values
-    return type_name === `log` ? [Math.max(min_val, math.LOG_EPS), max_val] : [min_val, max_val];
+    // log clamps to positive (arcsinh/linear take any value); clamp BOTH ends so all-negative
+    // data can't leave max <= the clamped min and invert/collapse the scale
+    if (type_name === `log`) {
+        const lo = Math.max(min_val, math.LOG_EPS);
+        return [lo, Math.max(max_val, lo)];
+    }
+    return [min_val, max_val];
 }
 // Advanced domain calculation with padding and nice boundaries (from ScatterPlot)
 export function get_nice_data_range(points, get_value, limits, scale_type, padding_factor, is_time = false) {
@@ -274,6 +293,13 @@ export function get_nice_data_range(points, get_value, limits, scale_type, paddi
     let data_min = min ?? min_ext ?? 0;
     let data_max = max ?? max_ext ?? 1;
     const type_name = get_scale_type_name(scale_type);
+    const can_snap_zero = min_ext !== undefined &&
+        max_ext !== undefined &&
+        min_ext < max_ext &&
+        !is_time &&
+        type_name !== `log`;
+    const snap_zero_min = can_snap_zero && min === null && min_ext === 0;
+    const snap_zero_max = can_snap_zero && max === null && max_ext === 0;
     // Apply padding *only if* limits were NOT provided
     if (min === null && max === null && points.length > 0) {
         if (data_min !== data_max) {
@@ -339,7 +365,7 @@ export function get_nice_data_range(points, get_value, limits, scale_type, paddi
     // Use D3's nice() to create pretty boundaries
     // For arcsinh, we don't use D3's nice() - just return padded domain
     if (type_name === `arcsinh`) {
-        return [data_min, data_max];
+        return [snap_zero_min ? 0 : data_min, snap_zero_max ? 0 : data_max];
     }
     // Create the scale with the *padded* data domain
     const scale = type_name === `log`
@@ -350,7 +376,7 @@ export function get_nice_data_range(points, get_value, limits, scale_type, paddi
         : scaleLinear().domain([data_min, data_max]);
     scale.nice();
     const [nice_min = data_min, nice_max = data_max] = scale.domain();
-    return [nice_min, nice_max];
+    return [snap_zero_min ? 0 : nice_min, snap_zero_max ? 0 : nice_max];
 }
 // Generate logarithmic ticks (from ScatterPlot)
 export function generate_log_ticks(min, max, ticks_option) {
@@ -400,16 +426,16 @@ export function create_color_scale(color_scale_config, auto_color_range) {
     const candidate_interpolator = Object.entries(d3_sc).find(([key]) => key === scheme)?.[1];
     const interpolator = typeof candidate_interpolator === `function`
         ? candidate_interpolator
-        : d3_sc.interpolateViridis;
+        : get_d3_interpolator(SCALE_DEFAULTS.scheme);
     const [min_val, max_val] = (typeof color_scale_config === `string` ? undefined : color_scale_config.value_range) ??
         auto_color_range;
     const scale_type = typeof color_scale_config === `string` ? undefined : color_scale_config.type;
     const type_name = get_scale_type_name(scale_type);
     if (type_name === `log`) {
-        return scaleSequentialLog(interpolator).domain([
-            Math.max(min_val, math.LOG_EPS),
-            Math.max(max_val, min_val * 1.1),
-        ]);
+        // clamp both ends (like create_scale): all-negative data otherwise yields an inverted
+        // [LOG_EPS, max<0] domain that maps every input to undefined
+        const lo = Math.max(min_val, math.LOG_EPS);
+        return scaleSequentialLog(interpolator).domain([lo, Math.max(max_val, lo * 1.1)]);
     }
     if (type_name === `arcsinh`) {
         // For arcsinh color scale, we create a custom scale that wraps the interpolator
@@ -436,7 +462,7 @@ function create_arcsinh_color_scale(interpolator, initial_domain, threshold) {
         const t_val = Math.asinh(value / safe_threshold);
         // Normalize to [0, 1]
         const normalized = t_max === t_min ? 0.5 : (t_val - t_min) / (t_max - t_min);
-        return interpolator(Math.max(0, Math.min(1, normalized)));
+        return interpolator(clamp01(normalized));
     });
     // Domain getter/setter for D3 compatibility - returns same scale instance
     scale.domain = function (new_domain) {
@@ -449,7 +475,7 @@ function create_arcsinh_color_scale(interpolator, initial_domain, threshold) {
 }
 // Create a size scale function from configuration
 export function create_size_scale(config, all_size_values) {
-    const [min_radius, max_radius] = config.radius_range ?? [2, 10];
+    const [min_radius, max_radius] = config.radius_range ?? SCALE_DEFAULTS.radius;
     const auto_range = all_size_values.length > 0
         ? extent(all_size_values.filter((val) => val !== null))
         : [0, 1];

package/dist/plot/core/svg.js

@@ -29,7 +29,6 @@ export function violin_path(grid_px, half_offsets_px, center, side, orient) {
     }
     return `M${pts.map(([x_pos, y_pos]) => `${x_pos},${y_pos}`).join(`L`)}Z`;
 }
-//
 // Generate SVG path for a bar with rounded corners on the "free" end (away from axis).
 // For vertical bars, rounds top corners. For horizontal bars, rounds right corners.
 export function bar_path(x, y, w, h, r, vertical = true) {

package/dist/plot/core/types/fills.d.ts

@@ -0,0 +1,101 @@
+export type FillBoundary = {
+    type: `series`;
+    series_idx: number;
+} | {
+    type: `series`;
+    series_id: string | number;
+} | {
+    type: `constant`;
+    value: number;
+} | {
+    type: `axis`;
+    axis: `x` | `x2` | `y` | `y2`;
+    value?: number;
+} | {
+    type: `function`;
+    fn: (coord: number) => number;
+} | {
+    type: `data`;
+    values: readonly number[];
+    x?: readonly number[];
+} | number;
+export interface FillGradient {
+    type: `linear` | `radial`;
+    angle?: number;
+    center?: {
+        x: number;
+        y: number;
+    };
+    stops: readonly [number, string][];
+}
+export interface FillEdgeStyle {
+    color?: string;
+    width?: number;
+    dash?: string;
+    opacity?: number;
+}
+export interface FillHoverStyle {
+    fill?: string;
+    fill_opacity?: number;
+    edge?: FillEdgeStyle;
+    cursor?: string;
+    scale?: number;
+    stroke?: string;
+    stroke_width?: number;
+}
+export interface FillHandlerEvent {
+    event: MouseEvent | KeyboardEvent;
+    region_idx: number;
+    region_id?: string | number;
+    x: number;
+    y: number;
+    px: number;
+    py: number;
+    label?: string;
+    metadata?: Record<string, unknown>;
+}
+export type LayerZIndex = `below-grid` | `below-lines` | `below-points` | `above-all`;
+export declare const FILL_CURVE_TYPES: readonly ["linear", "monotoneX", "monotoneY", "step", "stepBefore", "stepAfter", "basis", "cardinal", "catmullRom", "natural"];
+export type FillCurveType = (typeof FILL_CURVE_TYPES)[number];
+export interface FillRegion {
+    id?: string | number;
+    label?: string;
+    upper: FillBoundary;
+    lower: FillBoundary;
+    x_range?: [number | null, number | null];
+    y_range?: [number | null, number | null];
+    where?: (x: number, y_upper: number, y_lower: number) => boolean;
+    fill?: string | FillGradient;
+    fill_opacity?: number;
+    edge_upper?: FillEdgeStyle;
+    edge_lower?: FillEdgeStyle;
+    curve?: FillCurveType;
+    step_position?: number;
+    z_index?: LayerZIndex;
+    visible?: boolean;
+    hover_style?: FillHoverStyle;
+    on_click?: (event: FillHandlerEvent) => void;
+    on_hover?: (event: FillHandlerEvent | null) => void;
+    show_in_legend?: boolean;
+    legend_group?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ErrorBand {
+    series: {
+        type: `series`;
+        series_idx: number;
+    } | {
+        type: `series`;
+        series_id: string | number;
+    };
+    error: number | readonly number[] | {
+        upper: number | readonly number[];
+        lower: number | readonly number[];
+    };
+    fill?: string;
+    fill_opacity?: number;
+    edge_style?: FillEdgeStyle;
+    id?: string | number;
+    label?: string;
+    show_in_legend?: boolean;
+}

package/dist/plot/core/types/fills.js

@@ -0,0 +1,15 @@
+// Fill-region and error-band types for 2D plots (shaded areas between boundaries).
+// Self-contained leaf module re-exported via $lib/plot/core/types.
+// 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`,
+];

package/dist/plot/core/types/plot-3d.d.ts

@@ -0,0 +1,87 @@
+import type { Point3D, Vec2, Vec3 } from '../../../math';
+import type { AxisConfig, ControlsConfig, DataSeries, DisplayConfig, HandlerProps, Point, PointStyle, StyleOverrides } from './';
+export interface ScatterPoint3D<Metadata = Record<string, unknown>> extends Point<Metadata> {
+    z: number;
+}
+export interface DataSeries3D<Metadata = Record<string, unknown>> extends Omit<DataSeries<Metadata>, `y_axis` | `filtered_data`> {
+    z: readonly number[];
+    filtered_data?: InternalPoint3D<Metadata>[];
+}
+export interface InternalPoint3D<Metadata = Record<string, unknown>> extends ScatterPoint3D<Metadata> {
+    series_idx: number;
+    point_idx: number;
+    color_value?: number | null;
+    size_value?: number | null;
+    point_style?: PointStyle;
+}
+export type SurfaceType = `grid` | `parametric` | `triangulated`;
+export interface Surface3DConfig {
+    id?: string | number;
+    type: SurfaceType;
+    x_range?: Vec2;
+    y_range?: Vec2;
+    resolution?: number | Vec2;
+    z_fn?: (x: number, y: number) => number;
+    u_range?: Vec2;
+    v_range?: Vec2;
+    parametric_fn?: (u: number, v: number) => Point3D;
+    points?: Point3D[];
+    triangles?: Vec3[];
+    color?: string;
+    color_fn?: (x: number, y: number, z: number) => string;
+    opacity?: number;
+    wireframe?: boolean;
+    wireframe_color?: string;
+    wireframe_width?: number;
+    visible?: boolean;
+    double_sided?: boolean;
+}
+export interface AxisConfig3D extends AxisConfig {
+    show_plane?: boolean;
+    plane_opacity?: number;
+}
+export interface DisplayConfig3D extends DisplayConfig {
+    z_grid?: boolean;
+    z_zero_line?: boolean;
+    show_axes?: boolean;
+    show_axis_labels?: boolean;
+    show_bounding_box?: boolean;
+    show_grid?: boolean;
+    projections?: {
+        xy?: boolean;
+        xz?: boolean;
+        yz?: boolean;
+    };
+    projection_opacity?: number;
+    projection_scale?: number;
+}
+export interface Scatter3DHandlerProps<Metadata = Record<string, unknown>> extends Omit<HandlerProps<Metadata>, `x_axis` | `x2_axis` | `y_axis` | `y2_axis`> {
+    z: number;
+    x_axis: AxisConfig3D;
+    y_axis: AxisConfig3D;
+    z_axis: AxisConfig3D;
+    x_formatted: string;
+    y_formatted: string;
+    z_formatted: string;
+    color_value?: number | null;
+}
+export type Scatter3DHandlerEvent<Metadata = Record<string, unknown>> = Scatter3DHandlerProps<Metadata> & {
+    event?: MouseEvent;
+    point: InternalPoint3D<Metadata>;
+};
+export type CameraProjection3D = `perspective` | `orthographic`;
+export interface PlotConfig3D {
+    x_axis?: AxisConfig3D;
+    y_axis?: AxisConfig3D;
+    z_axis?: AxisConfig3D;
+    display?: DisplayConfig3D;
+}
+export interface StyleOverrides3D extends StyleOverrides {
+    point?: StyleOverrides[`point`] & {
+        sphere_segments?: number;
+    };
+}
+export interface ControlsConfig3D extends ControlsConfig {
+    show_camera_controls?: boolean;
+    show_surface_controls?: boolean;
+}

package/dist/plot/core/types/plot-3d.js

@@ -0,0 +1,4 @@
+// 3D plot types (scatter points, surfaces, axes, handlers) extending the 2D vocabulary.
+// Imports the 2D core types from the barrel and is re-exported by it; nothing in core depends on
+// these, so that re-export cycle is type-only (erased at build, hence harmless).
+export {};

package/dist/plot/core/types/reference-lines.d.ts

@@ -0,0 +1,140 @@
+import type { Vec3 } from '../../../math';
+import type { LayerZIndex } from './fills';
+export interface RefLineStyle {
+    color?: string;
+    width?: number;
+    dash?: string;
+    opacity?: number;
+}
+export interface RefLineAnnotation {
+    text: string;
+    position?: `start` | `center` | `end`;
+    side?: `above` | `below` | `left` | `right`;
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    gap?: number;
+    edge_padding?: number;
+    font_size?: string;
+    font_family?: string;
+    color?: string;
+    background?: string;
+    padding?: number;
+    rotate?: boolean;
+}
+export interface RefLineEvent {
+    event: MouseEvent | KeyboardEvent | FocusEvent;
+    line_idx: number;
+    line_id?: string | number;
+    type: RefLine[`type`];
+    label?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RefLineBase {
+    id?: string | number;
+    x_span?: [number | null, number | null];
+    y_span?: [number | null, number | null];
+    coord_mode?: `data` | `relative`;
+    x_axis?: `x1` | `x2`;
+    y_axis?: `y1` | `y2`;
+    style?: RefLineStyle;
+    annotation?: RefLineAnnotation;
+    z_index?: LayerZIndex;
+    visible?: boolean;
+    hover_style?: RefLineStyle;
+    on_click?: (event: RefLineEvent) => void;
+    on_hover?: (event: RefLineEvent | null) => void;
+    show_in_legend?: boolean;
+    label?: string;
+    legend_group?: string;
+    metadata?: Record<string, unknown>;
+}
+export type RefLineValue = number | Date | string;
+export type RefLine = RefLineBase & ({
+    type: `horizontal`;
+    y: RefLineValue;
+} | {
+    type: `vertical`;
+    x: RefLineValue;
+} | {
+    type: `diagonal`;
+    slope: number;
+    intercept: number;
+} | {
+    type: `segment`;
+    p1: [RefLineValue, RefLineValue];
+    p2: [RefLineValue, RefLineValue];
+} | {
+    type: `line`;
+    p1: [RefLineValue, RefLineValue];
+    p2: [RefLineValue, RefLineValue];
+});
+export declare const REF_LINE_STYLE_DEFAULTS: Required<RefLineStyle>;
+type Ref3DBase = Omit<RefLineBase, `coord_mode` | `x_axis` | `y_axis` | `style` | `hover_style` | `annotation` | `on_click` | `on_hover`> & {
+    z_span?: [number | null, number | null];
+};
+export interface RefLine3DBase extends Ref3DBase {
+    style?: RefLineStyle;
+    hover_style?: RefLineStyle;
+    annotation?: RefLineAnnotation;
+    on_click?: (event: {
+        line_idx: number;
+        line_id?: string | number;
+    }) => void;
+    on_hover?: (event: {
+        line_idx: number;
+        line_id?: string | number;
+    } | null) => void;
+}
+export type RefLine3D = RefLine3DBase & ({
+    type: `x-axis`;
+    y: number;
+    z: number;
+} | {
+    type: `y-axis`;
+    x: number;
+    z: number;
+} | {
+    type: `z-axis`;
+    x: number;
+    y: number;
+} | {
+    type: `segment`;
+    p1: Vec3;
+    p2: Vec3;
+} | {
+    type: `line`;
+    p1: Vec3;
+    p2: Vec3;
+});
+export interface RefPlaneStyle {
+    color?: string;
+    opacity?: number;
+    wireframe?: boolean;
+    wireframe_color?: string;
+    double_sided?: boolean;
+}
+export interface RefPlaneBase extends Ref3DBase {
+    style?: RefPlaneStyle;
+}
+export type RefPlane = RefPlaneBase & ({
+    type: `xy`;
+    z: number;
+} | {
+    type: `xz`;
+    y: number;
+} | {
+    type: `yz`;
+    x: number;
+} | {
+    type: `normal`;
+    normal: Vec3;
+    point: Vec3;
+} | {
+    type: `points`;
+    p1: Vec3;
+    p2: Vec3;
+    p3: Vec3;
+});
+export {};

package/dist/plot/core/types/reference-lines.js

@@ -0,0 +1,9 @@
+// Reference-line and reference-plane types for 2D and 3D plots.
+// Depends only on LayerZIndex (from ./fills) and math vectors; re-exported via $lib/plot/core/types.
+// Default style values for reference lines
+export const REF_LINE_STYLE_DEFAULTS = {
+    color: `currentColor`,
+    width: 1,
+    dash: ``,
+    opacity: 1,
+};