matterviz 0.4.0 → 0.4.2

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

@@ -1,12 +1,14 @@
+import type { PaneProps, PaneToggleProps } from '../../overlays';
+import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
 import type { D3SymbolName } from '../../labels';
-import type { Point2D, Point3D, Vec2, Vec3 } from '../../math';
-import type DraggablePane from '../../overlays/DraggablePane.svelte';
+import type { Point2D, Vec2 } from '../../math';
 import type { ComponentProps, Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import type { TweenOptions } from 'svelte/motion';
 import type { Sides } from './layout';
 import type PlotLegend from './components/PlotLegend.svelte';
 import type { TicksOption } from './scales';
+import type { FillGradient } from './types/fills';
 export type { TweenOptions } from 'svelte/motion';
 export type { BandwidthOption, BoxHandlerProps, BoxPlotSeries, ViolinKind, ViolinSide, WhiskerMode, } from '../box/box-plot';
 export type { CleaningConfig, CleaningQuality, CleaningResult, InstabilityResult, InvalidValueMode, LocalOutlierConfig, LocalOutlierResult, OscillationWeights, PhysicalBounds, SmoothingConfig, TruncationMode, } from './data-cleaning';
@@ -78,6 +80,7 @@ export interface BarStyle {
     ry?: number;
     [key: string]: unknown;
 }
+export type LineCurve = `linear` | `monotone` | `natural` | `step` | `basis` | `catmull-rom`;
 export interface LineStyle {
     color?: string;
     width?: number;
@@ -112,10 +115,12 @@ export interface DataSeries<Metadata = Record<string, unknown>> {
     label?: string;
     legend_group?: string;
     unit?: string;
+    axis_group?: string;
     line_style?: {
         stroke?: string;
         stroke_width?: number;
         line_dash?: string;
+        curve?: LineCurve;
     };
     filtered_data?: InternalPoint<Metadata>[];
     _id?: string | number;
@@ -189,6 +194,37 @@ export interface ArcsinhScaleConfig {
     threshold?: number;
 }
 export type ScaleType = `linear` | `log` | `arcsinh` | `time` | ArcsinhScaleConfig;
+export type ColorScaleConfig = {
+    type?: ScaleType;
+    scheme?: D3ColorSchemeName | D3InterpolateName;
+    value_range?: Vec2;
+};
+export type SizeScaleConfig = {
+    type?: ScaleType;
+    radius_range?: Vec2;
+    value_range?: Vec2;
+};
+export declare const COLOR_BAR_DEFAULTS: {
+    readonly width: 220;
+    readonly horizontal_bar_height: 16;
+    readonly binned_bar_height: 10;
+    readonly horizontal_footprint: {
+        readonly width: 220;
+        readonly height: 56;
+    };
+    readonly vertical_footprint: {
+        readonly width: 56;
+        readonly height: 100;
+    };
+};
+export declare const SCALE_DEFAULTS: {
+    scheme: D3InterpolateName;
+    color: ColorScaleConfig;
+    radius: Vec2;
+    binned_radius: Vec2;
+    size: SizeScaleConfig;
+    size_3d: SizeScaleConfig;
+};
 export declare const 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;
@@ -384,8 +420,8 @@ export interface PlotConfig {
 export interface ControlsConfig {
     show?: boolean;
     open?: boolean;
-    toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`];
-    pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`];
+    toggle_props?: PaneToggleProps;
+    pane_props?: PaneProps;
 }
 export interface PanConfig {
     enabled?: boolean;
@@ -412,8 +448,8 @@ export interface PlotControlsProps extends PlotConfig {
     show_ticks?: boolean;
     controls_title?: string;
     controls_class?: string;
-    toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`];
-    pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`];
+    toggle_props?: PaneToggleProps;
+    pane_props?: PaneProps;
 }
 export interface BasePlotProps {
     range_padding?: number;
@@ -421,8 +457,8 @@ export interface BasePlotProps {
     hovered?: boolean;
     show_controls?: boolean;
     controls_open?: boolean;
-    controls_toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`];
-    controls_pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`];
+    controls_toggle_props?: PaneToggleProps;
+    controls_pane_props?: PaneProps;
     fullscreen?: boolean;
     fullscreen_toggle?: boolean;
     change?: (data: Record<string, unknown> | null) => void;
@@ -446,326 +482,6 @@ export declare const DEFAULT_GRID_STYLE: {
 export declare const DEFAULT_MARKERS: "line+points";
 export declare const DEFAULT_SERIES_COLORS: readonly ["#4e79a7", "#f28e2c", "#e15759", "#76b7b2", "#59a14f", "#edc949", "#af7aa1", "#ff9da7", "#9c755f", "#bab0ab"];
 export declare const DEFAULT_SERIES_SYMBOLS: readonly ["Circle", "Square", "Triangle", "Cross", "Diamond", "Star", "Wye"];
-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;
-}
-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;
-}
-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 type * from './types/plot-3d';
+export * from './types/fills';
+export * from './types/reference-lines';

package/dist/plot/core/types.js

@@ -1,3 +1,24 @@
+// Shared defaults for color/size scales and colorbar layout (scatter, bar, binned-scatter, …)
+const COLOR_BAR_WIDTH = 220;
+export const COLOR_BAR_DEFAULTS = {
+    width: COLOR_BAR_WIDTH,
+    horizontal_bar_height: 16,
+    binned_bar_height: 10,
+    horizontal_footprint: { width: COLOR_BAR_WIDTH, height: 56 },
+    vertical_footprint: { width: 56, height: 100 },
+};
+// Shared color/size scale defaults for scatter, scatter-3d, binned-scatter, bar, …
+const VIRIDIS = `interpolateViridis`;
+const SCATTER_RADIUS = [2, 10];
+const BINNED_RADIUS = [4, 12];
+export const SCALE_DEFAULTS = {
+    scheme: VIRIDIS,
+    color: { type: `linear`, scheme: VIRIDIS, value_range: undefined },
+    radius: SCATTER_RADIUS,
+    binned_radius: BINNED_RADIUS,
+    size: { type: `linear`, radius_range: SCATTER_RADIUS, value_range: undefined },
+    size_3d: { type: `linear`, radius_range: [0.05, 0.2], value_range: undefined },
+};
 // Type guard for select value narrowing (avoids unsafe casts)
 const SCALE_TYPE_NAMES = new Set([`linear`, `log`, `arcsinh`, `time`]);
 export const is_scale_type_name = (val) => SCALE_TYPE_NAMES.has(val);
@@ -77,23 +98,5 @@ export const DEFAULT_SERIES_SYMBOLS = [
     `Star`,
     `Wye`,
 ];
-// Curve types supported for fill path generation (matching d3-shape curves)
-export const FILL_CURVE_TYPES = [
-    `linear`,
-    `monotoneX`,
-    `monotoneY`,
-    `step`,
-    `stepBefore`,
-    `stepAfter`,
-    `basis`,
-    `cardinal`,
-    `catmullRom`,
-    `natural`,
-];
-// Default style values for reference lines
-export const REF_LINE_STYLE_DEFAULTS = {
-    color: `currentColor`,
-    width: 1,
-    dash: ``,
-    opacity: 1,
-};
+export * from './types/fills';
+export * from './types/reference-lines';

package/dist/plot/core/utils/hierarchy-chart.d.ts

@@ -0,0 +1,51 @@
+import type { D3InterpolateName } from '../../../colors';
+import type { Vec2 } from '../../../math';
+import type { LegendItem } from '../types';
+import type { PositionedArc, SunburstLabelText, SunburstLayoutOptions, SunburstLayoutResult, SunburstNode, SunburstNodeHandlerProps } from '../../sunburst/sunburst';
+export declare function safe_hierarchy_layout<Metadata>(data: SunburstNode<Metadata> | SunburstNode<Metadata>[], opts: SunburstLayoutOptions): SunburstLayoutResult<Metadata>;
+export declare function compute_metric_colors<Metadata>(arcs: readonly PositionedArc<Metadata>[], color_values: ((arc: PositionedArc<Metadata>) => number | null) | undefined, color_scale: D3InterpolateName, color_range?: Vec2): {
+    range: Vec2;
+    colors: string[];
+} | null;
+export declare function compute_node_dim<Metadata>(arcs: readonly PositionedArc<Metadata>[], muted_ids: ReadonlySet<string | number>, hovered_idx: number | null): {
+    opacity: number;
+    label_opacity: number | undefined;
+}[];
+export declare function prune_muted_ids<Metadata>(arcs: readonly PositionedArc<Metadata>[], muted_ids: Set<string | number>): void;
+export declare function toggle_muted(muted_ids: Set<string | number>, id: string | number | undefined): void;
+export declare function hierarchy_legend_items<Metadata>(depth1_arcs: readonly PositionedArc<Metadata>[], muted_ids: ReadonlySet<string | number>, color_for: (arc: PositionedArc<Metadata>) => string): LegendItem[];
+export declare function node_handler_props<Metadata>(arcs: readonly PositionedArc<Metadata>[], arc: PositionedArc<Metadata>, color: string): SunburstNodeHandlerProps<Metadata>;
+export declare function selection_within(wrapper: HTMLElement | undefined): boolean;
+export declare function ancestor_chain<Metadata>(arcs: readonly PositionedArc<Metadata>[], zoom_root: PositionedArc<Metadata> | null): PositionedArc<Metadata>[];
+export interface HierarchyNodeInfo {
+    variants: {
+        text: string;
+        width: number;
+    }[];
+    aria: string;
+    fill: string;
+    label_fill: string;
+    clickable?: boolean;
+}
+export declare function compute_node_infos<Metadata>(arcs: readonly PositionedArc<Metadata>[], opts: {
+    label_text: SunburstLabelText;
+    value_format: string;
+    label_font: string;
+    color_for: (arc: PositionedArc<Metadata>) => string;
+    text_width: (text: string, font: string) => number;
+    contrast: (fill: string) => string;
+    clickable?: (arc: PositionedArc<Metadata>) => boolean;
+}): HierarchyNodeInfo[];
+export declare function svg_label_font(svg_element: SVGSVGElement | null): string;
+export declare const pointer_pos: (event: MouseEvent | FocusEvent | undefined, svg_element: SVGSVGElement | null) => {
+    x: number;
+    y: number;
+} | null;
+export declare const is_activation_key: (evt: KeyboardEvent) => boolean;
+export declare function handle_hierarchy_escape(evt: KeyboardEvent, ctx: {
+    wrapper: HTMLElement | undefined;
+    fullscreen: boolean;
+    zoomed: boolean;
+    zoom_out: () => void;
+    exit_fullscreen: () => void;
+}): void;