matterviz 0.4.0 → 0.4.2

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,
+};