matterviz 0.3.1 → 0.3.3

package/dist/plot/scales.js

@@ -1,5 +1,5 @@
 import * as math from '../math';
-import { get_arcsinh_threshold, get_scale_type_name, is_time_scale, } from './types';
+import { get_arcsinh_threshold, get_scale_type_name, is_time_scale } 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';
@@ -98,8 +98,8 @@ export function generate_arcsinh_ticks(min, max, threshold = 1, count = 10) {
     if (hi <= 0) {
         // Negative range: mirror the positive logic
         return generate_positive_arcsinh_ticks(-hi, -lo, safe_threshold, count)
-            .map((t) => -t)
-            .reverse();
+            .map((tick) => -tick)
+            .toReversed();
     }
     // Mixed range: symmetric ticks around zero (includes_zero is always true here)
     // For very small counts, we prioritize zero as the most meaningful tick
@@ -110,7 +110,7 @@ export function generate_arcsinh_ticks(min, max, threshold = 1, count = 10) {
     ticks.push(...pos_ticks.filter((t) => t > 0));
     // Add negative ticks (mirror of positive)
     const neg_ticks = generate_positive_arcsinh_ticks(0, -lo, safe_threshold, half_count);
-    ticks.push(...neg_ticks.filter((t) => t > 0).map((t) => -t));
+    ticks.push(...neg_ticks.filter((tick) => tick > 0).map((tick) => -tick));
     // For small counts where half_count is 0 or 1, ensure at least some boundary coverage
     if (half_count <= 1 && count >= 2) {
         // Add boundaries if not already present and we have room
@@ -185,7 +185,9 @@ export function create_scale(scale_type, domain, range) {
     const [min_val, max_val] = domain;
     const type_name = get_scale_type_name(scale_type);
     if (type_name === `log`) {
-        return scaleLog().domain([Math.max(min_val, math.LOG_EPS), max_val]).range(range);
+        return scaleLog()
+            .domain([Math.max(min_val, math.LOG_EPS), max_val])
+            .range(range);
     }
     if (type_name === `arcsinh`) {
         const threshold = get_arcsinh_threshold(scale_type);
@@ -221,9 +223,10 @@ options = {}) {
         const time_scale = scaleTime().domain([new Date(min_val), new Date(max_val)]);
         let count = 10; // default
         if (typeof ticks_option === `number`) {
-            count = ticks_option < 0
-                ? Math.ceil((max_val - min_val) / Math.abs(ticks_option) / 86_400_000) // milliseconds per day
-                : ticks_option;
+            count =
+                ticks_option < 0
+                    ? Math.ceil((max_val - min_val) / Math.abs(ticks_option) / 86_400_000) // milliseconds per day
+                    : ticks_option;
         }
         else if (typeof ticks_option === `string`) {
             count = ticks_option === `day` ? 30 : ticks_option === `month` ? 12 : 10;
@@ -248,9 +251,7 @@ options = {}) {
     // Arcsinh scale ticks
     if (type_name === `arcsinh`) {
         const threshold = get_arcsinh_threshold(scale_type);
-        const tick_count = typeof ticks_option === `number` && ticks_option > 0
-            ? ticks_option
-            : default_count;
+        const tick_count = typeof ticks_option === `number` && ticks_option > 0 ? ticks_option : default_count;
         return generate_arcsinh_ticks(min_val, max_val, threshold, tick_count);
     }
     // Linear scale with interval (negative number indicates interval)
@@ -260,9 +261,7 @@ options = {}) {
         return range(start, max_val + interval * interval_padding, interval);
     }
     // Default ticks using scale function
-    const tick_count = typeof ticks_option === `number` && ticks_option > 0
-        ? ticks_option
-        : default_count;
+    const tick_count = typeof ticks_option === `number` && ticks_option > 0 ? ticks_option : default_count;
     const ticks = scale_fn.ticks(tick_count);
     return ticks.map(Number);
 }
@@ -274,9 +273,7 @@ export function calculate_domain(values, scale_type = `linear`) {
     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];
+    return type_name === `log` ? [Math.max(min_val, math.LOG_EPS), max_val] : [min_val, max_val];
 }
 // Advanced domain calculation with padding and nice boundaries (from ScatterPlot)
 export function get_nice_data_range(points, get_value, range, scale_type, padding_factor, is_time = false) {
@@ -376,15 +373,11 @@ export function generate_log_ticks(min, max, ticks_option) {
     const max_power = Math.ceil(Math.log10(max));
     // For very wide ranges, extend the range to include more ticks
     const range_size = max_power - min_power;
-    const extended_min_power = range_size <= 2
-        ? min_power - 1
-        : min_power - Math.max(1, Math.floor(range_size / 4));
+    const extended_min_power = range_size <= 2 ? min_power - 1 : min_power - Math.max(1, Math.floor(range_size / 4));
     const extended_max_power = range_size <= 2 ? max_power + 1 : max_power;
-    const powers = range(extended_min_power, extended_max_power + 1).map((p) => Math.pow(10, p));
+    const powers = range(extended_min_power, extended_max_power + 1).map((power) => Math.pow(10, power));
     // For narrow ranges, include intermediate values
-    if (max_power - min_power < 3 &&
-        typeof ticks_option === `number` &&
-        ticks_option > 5) {
+    if (max_power - min_power < 3 && typeof ticks_option === `number` && ticks_option > 5) {
         const detailed_ticks = [];
         powers.forEach((power) => {
             detailed_ticks.push(power);
@@ -393,9 +386,9 @@ export function generate_log_ticks(min, max, ticks_option) {
             if (power * 5 <= Math.pow(10, extended_max_power))
                 detailed_ticks.push(power * 5);
         });
-        return detailed_ticks.filter((t) => t >= min && t <= max);
+        return detailed_ticks.filter((tick) => tick >= min && tick <= max);
     }
-    return powers.filter((p) => p >= min && p <= max);
+    return powers.filter((power) => power >= min && power <= max);
 }
 // Get custom label for a tick value if provided, otherwise return null
 export function get_tick_label(tick_value, ticks_option) {
@@ -406,18 +399,13 @@ export function get_tick_label(tick_value, ticks_option) {
 }
 // Create a color scale function from configuration
 export function create_color_scale(color_scale_config, auto_color_range) {
-    const scheme = typeof color_scale_config === `string`
-        ? color_scale_config
-        : color_scale_config.scheme;
+    const scheme = typeof color_scale_config === `string` ? color_scale_config : color_scale_config.scheme;
     const interpolator = (typeof d3_sc[scheme] === `function`
         ? d3_sc[scheme]
         : d3_sc.interpolateViridis);
-    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 [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([
@@ -465,7 +453,7 @@ function create_arcsinh_color_scale(interpolator, initial_domain, threshold) {
 export function create_size_scale(config, all_size_values) {
     const [min_radius, max_radius] = config.radius_range ?? [2, 10];
     const auto_range = all_size_values.length > 0
-        ? extent(all_size_values.filter((v) => v !== null))
+        ? extent(all_size_values.filter((val) => val !== null))
         : [0, 1];
     const [min_val, max_val] = config.value_range ?? auto_range;
     const safe_min = min_val ?? 0;

package/dist/plot/types.d.ts

@@ -1,10 +1,8 @@
 import type { D3SymbolName } from '../labels';
-import type { Vec3 } from '../math';
+import type { Vec2, Vec3 } from '../math';
 import type DraggablePane from '../overlays/DraggablePane.svelte';
-import type { SimulationNodeDatum } from 'd3-force';
 import type { ComponentProps, Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
-import type ColorBar from './ColorBar.svelte';
 import type PlotLegend from './PlotLegend.svelte';
 import type { TicksOption } from './scales';
 export interface TweenedOptions<T> {
@@ -27,6 +25,12 @@ export type Sides = {
     l?: number;
     r?: number;
 };
+export type InitialRanges = {
+    initial_x_range: Vec2;
+    initial_x2_range: Vec2;
+    initial_y_range: Vec2;
+    initial_y2_range: Vec2;
+};
 export type Point<Metadata = Record<string, unknown>> = {
     x: number;
     y: number;
@@ -93,6 +97,7 @@ export interface DataSeries<Metadata = Record<string, unknown>> {
     x: readonly number[];
     y: readonly number[];
     markers?: Markers;
+    x_axis?: `x1` | `x2`;
     y_axis?: `y1` | `y2`;
     color_values?: (number | null)[] | null;
     size_values?: readonly (number | null)[] | null;
@@ -138,6 +143,7 @@ export interface HandlerProps<Metadata = Record<string, unknown>> {
     label?: string | null;
     series_idx: number;
     x_axis: AxisConfig;
+    x2_axis?: AxisConfig;
     y_axis: AxisConfig;
     y2_axis?: AxisConfig;
     fullscreen?: boolean;
@@ -164,13 +170,16 @@ export interface BarHandlerProps<Metadata = Record<string, unknown>> extends Han
     orient_x: number;
     orient_y: number;
     active_y_axis: `y1` | `y2`;
+    active_x_axis: `x1` | `x2`;
     color: string;
+    category_label?: string;
 }
 export interface HistogramHandlerProps<Metadata = Record<string, unknown>> extends HandlerProps<Metadata> {
     value: number;
     count: number;
     property: string;
     active_y_axis: `y1` | `y2`;
+    active_x_axis: `x1` | `x2`;
 }
 export type TimeInterval = `day` | `month` | `year`;
 export type ScaleTypeName = `linear` | `log` | `arcsinh` | `time`;
@@ -179,6 +188,7 @@ export interface ArcsinhScaleConfig {
     threshold?: number;
 }
 export type ScaleType = `linear` | `log` | `arcsinh` | `time` | ArcsinhScaleConfig;
+export declare function is_scale_type_name(val: string): val is ScaleTypeName;
 export declare function get_scale_type_name(scale_type: ScaleType | undefined): ScaleTypeName;
 export declare function get_arcsinh_threshold(scale_type: ScaleType | undefined): number;
 export declare function is_time_scale(scale_type: ScaleType | undefined, format: string | undefined): boolean;
@@ -188,33 +198,23 @@ export type QuadrantCounts = {
     bottom_left: number;
     bottom_right: number;
 };
-export interface LabelNode<Metadata = Record<string, unknown>> extends SimulationNodeDatum {
-    id: string;
-    anchor_x: number;
-    anchor_y: number;
-    point_node: InternalPoint<Metadata>;
-    label_width: number;
-    label_height: number;
+export interface LabelPlacementWeights {
+    overlap?: number;
+    marker?: number;
+    leader_cross?: number;
+    leader_text?: number;
+    distance?: number;
+    bounds?: number;
 }
 export interface LabelPlacementConfig {
-    collision_strength: number;
-    link_strength: number;
-    link_distance: number;
-    placement_ticks: number;
-    link_distance_range?: [number | null, number | null];
+    sa_iterations?: number;
+    weights?: LabelPlacementWeights;
+    leader_line_threshold?: number;
+    max_labels?: number;
 }
 export type HoverConfig = {
     threshold_px: number;
 };
-export interface AnchorNode extends SimulationNodeDatum {
-    id: string;
-    fx: number;
-    fy: number;
-    point_radius: number;
-    show_color_bar?: boolean;
-    color_bar?: ComponentProps<typeof ColorBar> | null;
-    label_placement_config?: Partial<LabelPlacementConfig>;
-}
 export type LegendConfig = Omit<ComponentProps<typeof PlotLegend>, `series_data` | `on_drag_start` | `on_drag` | `on_drag_end`> & {
     margin?: number | Sides;
     tween?: TweenedOptions<XyObj>;
@@ -246,19 +246,21 @@ export type UserContentProps = {
     height: number;
     width: number;
     x_scale_fn: (x: number) => number;
+    x2_scale_fn?: (x: number) => number;
     y_scale_fn: (y: number) => number;
     y2_scale_fn?: (y: number) => number;
     pad: Required<Sides>;
-    x_range: [number, number];
-    y_range: [number, number];
-    y2_range?: [number, number];
+    x_range: Vec2;
+    x2_range?: Vec2;
+    y_range: Vec2;
+    y2_range?: Vec2;
     fullscreen: boolean;
 };
 export type Orientation = `vertical` | `horizontal`;
 export type BarMode = `overlay` | `stacked` | `grouped`;
 export interface BarSeries<Metadata = Record<string, unknown>> {
     id?: string | number;
-    x: readonly number[];
+    x: readonly (number | string)[];
     y: readonly number[];
     label?: string;
     legend_group?: string;
@@ -268,6 +270,7 @@ export interface BarSeries<Metadata = Record<string, unknown>> {
     metadata?: Metadata[] | Metadata;
     labels?: readonly (string | null | undefined)[];
     render_mode?: `bar` | `line`;
+    x_axis?: `x1` | `x2`;
     y_axis?: `y1` | `y2`;
     line_style?: {
         stroke_width?: number;
@@ -295,6 +298,7 @@ export interface AxisOption {
     unit?: string;
 }
 export type Y2SyncMode = `none` | `synced` | `align`;
+export declare function is_y2_sync_mode(val: string): val is Y2SyncMode;
 export interface Y2SyncConfig {
     mode: Y2SyncMode;
     align_value?: number;
@@ -313,6 +317,7 @@ export interface AxisConfig {
     options?: AxisOption[];
     selected_key?: string;
     sync?: Y2SyncConfig | Y2SyncMode;
+    categories?: readonly string[];
 }
 export interface DataLoaderResult<Metadata = Record<string, unknown>, SeriesType = DataSeries<Metadata>> {
     series: SeriesType[];
@@ -331,15 +336,18 @@ export interface ColorScaleOption {
     scale: string | ((t: number) => string);
 }
 export type ColorBarDataLoaderFn = (property_key: string) => Promise<{
-    range: [number, number];
+    range: Vec2;
     title?: string;
 }>;
 export interface DisplayConfig {
     x_grid?: boolean;
+    x2_grid?: boolean;
     y_grid?: boolean;
     y2_grid?: boolean;
     x_zero_line?: boolean;
+    x2_zero_line?: boolean;
     y_zero_line?: boolean;
+    y2_zero_line?: boolean;
 }
 export interface StyleOverrides {
     point?: {
@@ -359,9 +367,10 @@ export interface StyleOverrides {
     show_points?: boolean;
     show_lines?: boolean;
 }
-export type AxisKey = `x` | `y` | `y2`;
+export type AxisKey = `x` | `x2` | `y` | `y2`;
 export interface PlotConfig {
     x_axis?: AxisConfig;
+    x2_axis?: AxisConfig;
     y_axis?: AxisConfig;
     y2_axis?: AxisConfig;
     display?: DisplayConfig;
@@ -388,9 +397,11 @@ export interface PlotControlsProps extends PlotConfig {
     controls_open?: boolean;
     children?: Snippet<[ControlsState]>;
     post_children?: Snippet<[ControlsState]>;
-    auto_x_range?: [number, number];
-    auto_y_range?: [number, number];
-    auto_y2_range?: [number, number];
+    auto_x_range?: Vec2;
+    auto_x2_range?: Vec2;
+    auto_y_range?: Vec2;
+    auto_y2_range?: Vec2;
+    has_x2_points?: boolean;
     has_y2_points?: boolean;
     show_ticks?: boolean;
     controls_title?: string;
@@ -400,6 +411,7 @@ export interface PlotControlsProps extends PlotConfig {
 }
 export interface BasePlotProps {
     x_range?: [number | null, number | null];
+    x2_range?: [number | null, number | null];
     y_range?: [number | null, number | null];
     y2_range?: [number | null, number | null];
     range_padding?: number;
@@ -457,12 +469,12 @@ export type SurfaceType = `grid` | `parametric` | `triangulated`;
 export interface Surface3DConfig {
     id?: string | number;
     type: SurfaceType;
-    x_range?: [number, number];
-    y_range?: [number, number];
-    resolution?: number | [number, number];
+    x_range?: Vec2;
+    y_range?: Vec2;
+    resolution?: number | Vec2;
     z_fn?: (x: number, y: number) => number;
-    u_range?: [number, number];
-    v_range?: [number, number];
+    u_range?: Vec2;
+    v_range?: Vec2;
     parametric_fn?: (u: number, v: number) => XyzObj;
     points?: XyzObj[];
     triangles?: Vec3[];
@@ -541,7 +553,7 @@ export type FillBoundary = {
     value: number;
 } | {
     type: `axis`;
-    axis: `x` | `y` | `y2`;
+    axis: `x` | `x2` | `y` | `y2`;
     value?: number;
 } | {
     type: `function`;
@@ -664,6 +676,7 @@ export interface RefLineBase {
     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;
@@ -830,7 +843,7 @@ export interface CleaningQuality {
     oscillation_score?: number;
     bounds_violations: number;
     outliers_removed?: number;
-    stable_range?: [number, number];
+    stable_range?: Vec2;
     truncated_at_x?: number;
 }
 export interface CleaningResult<T = DataSeries> {

package/dist/plot/types.js

@@ -1,3 +1,8 @@
+// Type guard for select value narrowing (avoids unsafe casts)
+const SCALE_TYPE_NAMES = new Set([`linear`, `log`, `arcsinh`, `time`]);
+export function is_scale_type_name(val) {
+    return SCALE_TYPE_NAMES.has(val);
+}
 // Helper to normalize ScaleType to base type name
 export function get_scale_type_name(scale_type) {
     if (!scale_type)
@@ -27,6 +32,11 @@ export function is_time_scale(scale_type, format) {
     // 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 function is_y2_sync_mode(val) {
+    return Y2_SYNC_MODES.has(val);
+}
 export const LINE_TYPES = [`solid`, `dashed`, `dotted`];
 // Define grid cell identifiers
 export const CELLS_3X3 = [
@@ -40,15 +50,10 @@ export const CELLS_3X3 = [
     `bottom-center`,
     `bottom-right`,
 ];
-export const CORNER_CELLS = [
-    `top-left`,
-    `top-right`,
-    `bottom-left`,
-    `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: `var(--border-color, gray)`,
     'stroke-dasharray': `4`,
     'stroke-width': `1`,
 };

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

@@ -1,21 +1,38 @@
 import type { AxisConfig, DataSeries, XyObj } from '..';
 import type { PlotScaleFn } from '../scales';
-import type { LabelPlacementConfig } from '../types';
-type ScaleFn = PlotScaleFn;
-export interface AnchorNode {
-    id: string;
-    fx: number;
-    fy: number;
-    point_radius: number;
+import type { LabelPlacementConfig, LabelPlacementWeights } from '../types';
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
 }
-export declare function compute_label_positions(filtered_series: DataSeries[], config: LabelPlacementConfig & {
-    max_labels?: number;
-    charge_strength?: number;
-    charge_distance_max?: number;
-}, scales: {
-    x_scale_fn: ScaleFn;
-    y_scale_fn: ScaleFn;
-    y2_scale_fn: ScaleFn;
+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 declare function parse_font_size(size_str?: string): number;
+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 generate_candidates(ax: number, ay: number, point_radius: number, label_w: number, label_h: number, gap: number): XyObj[];
+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;