matterviz 0.3.6 → 0.4.0

package/dist/plot/scatter/ScatterPlot.svelte.d.ts

@@ -0,0 +1,96 @@
+import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
+import type { Point2D } from '../../math';
+import type { AxisLoadError, BasePlotProps, ControlsConfig, DataLoaderFn, DataSeries, ErrorBand, FillHandlerEvent, FillRegion, HoverConfig, InternalPoint, LabelPlacementConfig, LegendConfig, PanConfig, PlotConfig, Point, RefLine, RefLineEvent, ScaleType, ScatterHandlerEvent, ScatterHandlerProps, StyleOverrides, UserContentProps } from '..';
+import { ColorBar } from '..';
+import type { ComponentProps, Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type TweenOptions } from 'svelte/motion';
+import type { Sides } from '../core/layout';
+declare function $$render<Metadata extends Record<string, unknown> = Record<string, unknown>>(): {
+    props: HTMLAttributes<HTMLDivElement> & Omit<BasePlotProps, "change"> & PlotConfig & {
+        series?: DataSeries<Metadata>[];
+        styles?: StyleOverrides;
+        controls?: ControlsConfig;
+        current_x_value?: number | null;
+        tooltip_point?: InternalPoint<Metadata> | null;
+        selected_point?: {
+            series_idx: number;
+            point_idx: number;
+        } | null;
+        tooltip?: Snippet<[ScatterHandlerProps<Metadata>]>;
+        user_content?: Snippet<[UserContentProps]>;
+        header_controls?: Snippet<[{
+            height: number;
+            width: number;
+            fullscreen: boolean;
+        }]>;
+        controls_extra?: Snippet<[{
+            styles: StyleOverrides;
+            selected_series_idx: number;
+        } & Required<PlotConfig>]>;
+        change?: (data: (Point<Metadata> & {
+            series: DataSeries<Metadata>;
+        }) | null) => void;
+        color_scale?: {
+            type?: ScaleType;
+            scheme?: D3ColorSchemeName | D3InterpolateName;
+            value_range?: [number, number];
+        } | D3InterpolateName;
+        size_scale?: {
+            type?: ScaleType;
+            radius_range?: [number, number];
+            value_range?: [number, number];
+        };
+        color_bar?: (ComponentProps<typeof ColorBar> & {
+            margin?: number | Sides;
+            tween?: TweenOptions<Point2D>;
+            responsive?: boolean;
+            axis_clearance?: number;
+        }) | null;
+        label_placement_config?: Partial<LabelPlacementConfig>;
+        hover_config?: Partial<HoverConfig>;
+        legend?: LegendConfig | null;
+        point_tween?: TweenOptions<Point2D>;
+        line_tween?: TweenOptions<string>;
+        point_events?: Record<string, (payload: {
+            point: InternalPoint<Metadata>;
+            event: Event;
+        }) => void>;
+        on_point_click?: (data: ScatterHandlerEvent<Metadata>) => void;
+        on_point_hover?: (data: ScatterHandlerEvent<Metadata> | null) => void;
+        fill_regions?: FillRegion[];
+        error_bands?: ErrorBand[];
+        on_fill_click?: (event: FillHandlerEvent) => void;
+        on_fill_hover?: (event: FillHandlerEvent | null) => void;
+        ref_lines?: RefLine[];
+        on_ref_line_click?: (event: RefLineEvent) => void;
+        on_ref_line_hover?: (event: RefLineEvent | null) => void;
+        selected_series_idx?: number;
+        wrapper?: HTMLDivElement;
+        data_loader?: DataLoaderFn<Metadata>;
+        on_axis_change?: (axis: `x` | `x2` | `y` | `y2`, key: string, new_series: DataSeries<Metadata>[]) => void;
+        on_error?: (error: AxisLoadError) => void;
+        pan?: PanConfig;
+    };
+    exports: {};
+    bindings: "display" | "fullscreen" | "series" | "hovered" | "ref_lines" | "x_axis" | "y_axis" | "x2_axis" | "y2_axis" | "wrapper" | "tooltip_point" | "fill_regions" | "selected_series_idx";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Metadata extends Record<string, unknown> = Record<string, unknown>> {
+    props(): ReturnType<typeof $$render<Metadata>>['props'];
+    events(): ReturnType<typeof $$render<Metadata>>['events'];
+    slots(): ReturnType<typeof $$render<Metadata>>['slots'];
+    bindings(): "display" | "fullscreen" | "series" | "hovered" | "ref_lines" | "x_axis" | "y_axis" | "x2_axis" | "y2_axis" | "wrapper" | "tooltip_point" | "fill_regions" | "selected_series_idx";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Metadata extends Record<string, unknown> = Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Metadata>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Metadata>['props']>, ReturnType<__sveltets_Render<Metadata>['events']>, ReturnType<__sveltets_Render<Metadata>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Metadata>['bindings']>;
+    } & ReturnType<__sveltets_Render<Metadata>['exports']>;
+    <Metadata extends Record<string, unknown> = Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<Metadata>['props']> & {}): ReturnType<__sveltets_Render<Metadata>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const ScatterPlot: $$IsomorphicComponent;
+type ScatterPlot<Metadata extends Record<string, unknown> = Record<string, unknown>> = InstanceType<typeof ScatterPlot<Metadata>>;
+export default ScatterPlot;

package/dist/plot/scatter/ScatterPlotControls.svelte

@@ -0,0 +1,307 @@
+<script lang="ts">
+  import { SettingsSection } from '../../layout'
+  import { PlotControls } from '..'
+  import type {
+    DataSeries,
+    PlotConfig,
+    PlotControlsProps,
+    StyleOverrides,
+  } from '../core/types'
+  import { unique_id } from '../core/utils'
+  import { DEFAULTS } from '../../settings'
+  import type { Snippet } from 'svelte'
+  import { tooltip } from 'svelte-multiselect/attachments'
+
+  // Unique ID prefix to avoid conflicts when multiple instances on same page
+  const uid = unique_id(`scatter-ctrl`)
+
+  let {
+    series = [],
+    x_axis = $bindable({}),
+    x2_axis = $bindable({}),
+    y_axis = $bindable({}),
+    y2_axis = $bindable({}),
+    display = $bindable({}),
+    styles = $bindable({}),
+    selected_series_idx = $bindable(0),
+    on_touch,
+    children,
+    ...rest
+  }: Omit<PlotControlsProps, `children` | `post_children`> & {
+    series?: readonly DataSeries[]
+    styles?: StyleOverrides
+    selected_series_idx?: number
+    on_touch?: (key: string) => void
+    children?: Snippet<
+      [{ styles: StyleOverrides; selected_series_idx: number } & Required<PlotConfig>]
+    >
+  } = $props()
+
+  let non_null_series = $derived(series.filter((srs) => srs != null))
+  let visible_series = $derived(
+    non_null_series.filter((srs) => (srs.visible ?? true)),
+  )
+  let has_multiple_series = $derived(non_null_series.length > 1)
+
+  // Derive what marker types are present, and whether color/size are data-driven
+  const markers_include = (mode: string) =>
+    visible_series.some((srs) => (srs?.markers ?? `line+points`).includes(mode))
+  let has_any_lines = $derived(markers_include(`line`))
+  let has_any_points = $derived(markers_include(`points`))
+  let has_color_data = $derived(
+    visible_series.some((srs) => srs?.color_values?.some((val) => val != null)),
+  )
+  let has_size_data = $derived(
+    visible_series.some((srs) => srs?.size_values?.some((val) => val != null)),
+  )
+
+  $effect(() => { // Initialize show_points/show_lines from defaults
+    styles.show_points ??= DEFAULTS.scatter.show_points
+    styles.show_lines ??= DEFAULTS.scatter.show_lines
+  })
+
+  const touch = ({ target }: Event) => {
+    if (!(target instanceof Element)) return
+    const key = target.closest(`[data-key]`)?.getAttribute(`data-key`)
+    if (key) on_touch?.(key)
+  }
+</script>
+
+<PlotControls
+  bind:x_axis
+  bind:x2_axis
+  bind:y_axis
+  bind:y2_axis
+  bind:display
+  show_controls
+  {...rest}
+>
+  {@render children?.({
+      x_axis,
+      x2_axis,
+      y_axis,
+      y2_axis,
+      display,
+      styles,
+      selected_series_idx,
+    })}
+  {#if has_any_points || has_any_lines}
+    <SettingsSection
+      title="Markers"
+      current_values={{ show_points: styles.show_points, show_lines: styles.show_lines }}
+      on_reset={() => {
+        styles.show_points = DEFAULTS.scatter.show_points
+        styles.show_lines = DEFAULTS.scatter.show_lines
+      }}
+      style="display: flex; flex-wrap: wrap; gap: 1ex"
+    >
+      {#if has_any_points}
+        <label
+          {@attach tooltip({ content: `Toggle visibility of data points in the scatter plot` })}
+        >
+          <input type="checkbox" bind:checked={styles.show_points} /> Show points
+        </label>
+      {/if}
+      {#if has_any_lines}
+        <label
+          {@attach tooltip({ content: `Toggle visibility of connecting lines between data points` })}
+        >
+          <input type="checkbox" bind:checked={styles.show_lines} /> Show lines
+        </label>
+      {/if}
+    </SettingsSection>
+  {/if}
+
+  {#snippet post_children()}
+    <!-- Series Selection (for multi-series style controls) -->
+    {#if has_multiple_series}
+      <div class="pane-row">
+        <label for="{uid}-series">Series</label>
+        <select bind:value={selected_series_idx} id="{uid}-series">
+          {#each series as srs, idx (idx)}
+            {#if srs}
+              <option value={idx}>
+                {srs.label ?? `Series ${idx + 1}`}
+              </option>
+            {/if}
+          {/each}
+        </select>
+      </div>
+    {/if}
+
+    <!-- Point Style Controls: only when points exist and are visible -->
+    {#if has_any_points && styles.show_points}
+      <SettingsSection
+        title="Point Style"
+        current_values={styles.point ?? {}}
+        on_reset={() => {
+          styles.point = { ...DEFAULTS.scatter.point }
+          Object.keys(DEFAULTS.scatter.point).forEach((key) => on_touch?.(`point.${key}`))
+        }}
+        oninput={touch}
+      >
+        {#if styles.point}
+          {#if !has_size_data}
+            <div class="pane-row" data-key="point.size">
+              <label for="{uid}-point-size">Size:</label>
+              <input
+                id="{uid}-point-size"
+                type="range"
+                min="1"
+                max="20"
+                step="0.5"
+                bind:value={styles.point.size}
+              />
+              <input
+                type="number"
+                min="1"
+                max="20"
+                step="0.5"
+                bind:value={styles.point.size}
+              />
+            </div>
+          {/if}
+          {#if !has_color_data}
+            <div class="pane-row" data-key="point.color">
+              <label for="{uid}-point-color">Color:</label>
+              <input
+                id="{uid}-point-color"
+                type="color"
+                bind:value={styles.point.color}
+              />
+            </div>
+          {/if}
+          <div class="pane-row" data-key="point.opacity">
+            <label for="{uid}-point-opacity">Opacity:</label>
+            <input
+              id="{uid}-point-opacity"
+              type="range"
+              min="0"
+              max="1"
+              step="0.05"
+              bind:value={styles.point.opacity}
+            />
+            <input
+              type="number"
+              min="0"
+              max="1"
+              step="0.05"
+              bind:value={styles.point.opacity}
+            />
+          </div>
+          <div class="pane-row" data-key="point.stroke_width">
+            <label for="{uid}-point-stroke-width">Stroke Width:</label>
+            <input
+              id="{uid}-point-stroke-width"
+              type="range"
+              min="0"
+              max="5"
+              step="0.1"
+              bind:value={styles.point.stroke_width}
+            />
+            <input
+              type="number"
+              min="0"
+              max="5"
+              step="0.1"
+              bind:value={styles.point.stroke_width}
+            />
+          </div>
+          <div class="pane-row" data-key="point.stroke_color">
+            <label for="{uid}-point-stroke-color">Stroke Color:</label>
+            <input
+              id="{uid}-point-stroke-color"
+              type="color"
+              bind:value={styles.point.stroke_color}
+            />
+          </div>
+          <div class="pane-row" data-key="point.stroke_opacity">
+            <label for="{uid}-point-stroke-opacity">Stroke Opacity:</label>
+            <input
+              id="{uid}-point-stroke-opacity"
+              type="range"
+              min="0"
+              max="1"
+              step="0.05"
+              bind:value={styles.point.stroke_opacity}
+            />
+            <input
+              type="number"
+              min="0"
+              max="1"
+              step="0.05"
+              bind:value={styles.point.stroke_opacity}
+            />
+          </div>
+        {/if}
+      </SettingsSection>
+    {/if}
+
+    <!-- Line Style Controls: only when lines exist and are visible -->
+    {#if has_any_lines && styles.show_lines}
+      <SettingsSection
+        title="Line Style"
+        current_values={styles.line ?? {}}
+        on_reset={() => {
+          styles.line = { ...DEFAULTS.scatter.line }
+          Object.keys(DEFAULTS.scatter.line).forEach((key) => on_touch?.(`line.${key}`))
+        }}
+        oninput={touch}
+      >
+        {#if styles.line}
+          <div class="pane-row" data-key="line.width">
+            <label for="{uid}-line-width">Width:</label>
+            <input
+              id="{uid}-line-width"
+              type="range"
+              min="0.5"
+              max="10"
+              step="0.5"
+              bind:value={styles.line.width}
+            />
+            <input
+              type="number"
+              min="0.5"
+              max="10"
+              step="0.5"
+              bind:value={styles.line.width}
+            />
+          </div>
+          {#if !has_color_data}
+            <div class="pane-row" data-key="line.color">
+              <label for="{uid}-line-color">Color:</label>
+              <input id="{uid}-line-color" type="color" bind:value={styles.line.color} />
+            </div>
+          {/if}
+          <div class="pane-row" data-key="line.opacity">
+            <label for="{uid}-line-opacity">Opacity:</label>
+            <input
+              id="{uid}-line-opacity"
+              type="range"
+              min="0"
+              max="1"
+              step="0.05"
+              bind:value={styles.line.opacity}
+            />
+            <input
+              type="number"
+              min="0"
+              max="1"
+              step="0.05"
+              bind:value={styles.line.opacity}
+            />
+          </div>
+          <div class="pane-row" data-key="line.dash">
+            <label for="{uid}-line-style">Style:</label>
+            <select id="{uid}-line-style" bind:value={styles.line.dash}>
+              <option value="solid">Solid</option>
+              <option value="4,4">Dashed</option>
+              <option value="2,2">Dotted</option>
+              <option value="8,4,2,4">Dash-dot</option>
+            </select>
+          </div>
+        {/if}
+      </SettingsSection>
+    {/if}
+  {/snippet}
+</PlotControls>

package/dist/plot/scatter/ScatterPlotControls.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { DataSeries, PlotConfig, PlotControlsProps, StyleOverrides } from '../core/types';
+import type { Snippet } from 'svelte';
+type $$ComponentProps = Omit<PlotControlsProps, `children` | `post_children`> & {
+    series?: readonly DataSeries[];
+    styles?: StyleOverrides;
+    selected_series_idx?: number;
+    on_touch?: (key: string) => void;
+    children?: Snippet<[
+        {
+            styles: StyleOverrides;
+            selected_series_idx: number;
+        } & Required<PlotConfig>
+    ]>;
+};
+declare const ScatterPlotControls: import("svelte").Component<$$ComponentProps, {}, "display" | "x_axis" | "y_axis" | "x2_axis" | "y2_axis" | "selected_series_idx" | "styles">;
+type ScatterPlotControls = ReturnType<typeof ScatterPlotControls>;
+export default ScatterPlotControls;

package/dist/plot/scatter/ScatterPoint.svelte

@@ -0,0 +1,182 @@
+<script lang="ts">
+  import { type D3SymbolName, symbol_map } from '../../labels'
+  import type { HoverStyle, LabelStyle, Point } from '..'
+  import type { Point2D } from '../../math'
+  import type { PointStyle } from '../core/types'
+  import { estimate_label_size, label_leader_segment } from '../core/utils/label-placement'
+  import { DEFAULTS } from '../../settings'
+  import * as d3_symbols from 'd3-shape'
+  import { symbol } from 'd3-shape'
+  import { cubicOut } from 'svelte/easing'
+  import type { SVGAttributes } from 'svelte/elements'
+  import { Tween, type TweenOptions } from 'svelte/motion'
+
+  let {
+    x,
+    y,
+    style = {},
+    hover = {},
+    label = {},
+    offset = { x: 0, y: 0 },
+    point_tween = $bindable({}),
+    origin = $bindable({ x: 0, y: 0 }),
+    is_hovered = false,
+    is_selected = false,
+    is_dimmed = false,
+    leader_line_threshold = 15,
+    ...rest
+  }: Omit<SVGAttributes<SVGGElement>, `style` | `offset` | `origin` | `transform`> & {
+    x: number
+    y: number
+    style?: PointStyle
+    hover?: HoverStyle
+    label?: LabelStyle
+    offset?: Point[`offset`]
+    point_tween?: TweenOptions<Point2D>
+    origin?: Point2D
+    is_hovered?: boolean
+    is_selected?: boolean
+    is_dimmed?: boolean
+    leader_line_threshold?: number
+  } = $props()
+
+  // get the SVG path data as 'd' attribute
+  function get_symbol_path(): string {
+    const symbol_key: D3SymbolName = style.symbol_type ?? DEFAULTS.scatter.symbol_type
+    const symbol_type = symbol_map[symbol_key] ?? d3_symbols.symbolCircle
+    const size = style.symbol_size ?? Math.PI * (style.radius ?? 2) ** 2
+    return symbol().type(symbol_type).size(size)() || ``
+  }
+
+  let marker_path = $derived.by(get_symbol_path)
+
+  const default_tween_props: TweenOptions<Point2D> = {
+    duration: 600,
+    easing: cubicOut,
+  }
+  // Single tween for {x, y} coordinates
+  const tweened_coords = new Tween(origin, { ...default_tween_props, ...point_tween })
+
+  $effect.pre(() => {
+    tweened_coords.target = { x: x + offset.x, y: y + offset.y }
+  })
+</script>
+
+<g
+  transform="translate({tweened_coords.current.x} {tweened_coords.current.y})"
+  style:--hover-scale={hover.scale ?? 1.5}
+  style:--hover-stroke={hover.stroke ?? `white`}
+  style:--hover-stroke-width="{hover.stroke_width ?? 0}px"
+  style:--hover-brightness={hover.brightness ?? 1.2}
+  {...rest}
+>
+  {#if is_selected}
+    <circle
+      r={(style.radius ?? 4) * 2.5}
+      class="effect-ring selected"
+      fill="var(--point-fill-color, {style.fill ?? `cornflowerblue`})"
+      stroke="var(--effect-ring-stroke, white)"
+      stroke-width="var(--effect-ring-stroke-width, 1)"
+    />
+  {:else if style.is_highlighted && style.highlight_effect?.match(/pulse|glow/)}
+    <circle
+      r={(style.radius ?? 4) * 2}
+      class="effect-ring {style.highlight_effect}"
+      fill={style.highlight_color ?? `#ff4444`}
+      stroke="var(--effect-ring-stroke, white)"
+      stroke-width="var(--effect-ring-stroke-width, 1)"
+    />
+  {/if}
+  <path
+    d={marker_path}
+    stroke={style.stroke ?? `transparent`}
+    stroke-width={style.stroke_width ?? 1}
+    fill-opacity={style.fill_opacity ?? 1}
+    stroke-opacity={style.stroke_opacity ?? 1}
+    fill="var(--point-fill-color, {style.fill ?? `black`})"
+    class="marker"
+    class:is-hovered={is_hovered && (hover.enabled ?? true)}
+    class:is-dimmed={is_dimmed}
+    style:cursor={style.cursor}
+  />
+  {#if label.text}
+    {@const offset_x = label.offset?.x ?? 10}
+    {@const offset_y = label.offset?.y ?? 0}
+    {@const displacement = Math.hypot(offset_x, offset_y)}
+    {@const leader_line = displacement > leader_line_threshold ? label_leader_segment({
+      point: { x: 0, y: 0 },
+      point_radius: style.radius ?? 3,
+      label_center: { x: offset_x, y: offset_y },
+      label_size: label.size ?? estimate_label_size(label.text, label.font_size),
+      min_length: 6,
+    }) : null}
+    {#if leader_line}
+      <line
+        x1={leader_line.x1}
+        y1={leader_line.y1}
+        x2={leader_line.x2}
+        y2={leader_line.y2}
+        class="leader-line"
+        stroke="var(--scatter-leader-line-color, #888)"
+        stroke-width="var(--scatter-leader-line-width, 0.8)"
+        stroke-dasharray="var(--scatter-leader-line-dash, 2 2)"
+        stroke-opacity="var(--scatter-leader-line-opacity, 0.6)"
+      />
+    {/if}
+    <text
+      x={offset_x}
+      y={offset_y}
+      text-anchor={label.auto_placement ? `middle` : undefined}
+      style:font-size={label.font_size ?? `10px`}
+      style:font-family={label.font_family ?? `sans-serif`}
+      fill="var(--scatter-point-label-fill, currentColor)"
+      dominant-baseline="middle"
+      class="label-text"
+    >
+      {label.text}
+    </text>
+  {/if}
+</g>
+
+<style>
+  .marker {
+    transition: var(--scatter-point-transition, all 0.2s);
+  }
+  .marker.is-hovered {
+    transform: scale(var(--hover-scale));
+    stroke: var(--hover-stroke);
+    stroke-width: var(--hover-stroke-width);
+    filter: brightness(var(--hover-brightness));
+  }
+  .marker.is-dimmed {
+    opacity: var(--scatter-point-dimmed-opacity, 0.25);
+  }
+  .effect-ring {
+    pointer-events: none;
+    animation: ring-pulse var(--effect-ring-duration, 1s) ease-in-out
+      var(--effect-ring-iterations, infinite);
+  }
+  .effect-ring.pulse {
+    --effect-ring-duration: 1.2s;
+  }
+  .effect-ring.glow {
+    --effect-ring-duration: 1.5s;
+    filter: blur(3px);
+  }
+  @keyframes ring-pulse {
+    0%, 100% {
+      opacity: 0.3;
+      transform: scale(1);
+    }
+    50% {
+      opacity: 0.7;
+      transform: scale(1.2);
+    }
+  }
+  .label-text {
+    pointer-events: var(--scatter-point-label-pointer-events, none);
+  }
+  .leader-line {
+    pointer-events: none;
+  }
+</style>

package/dist/plot/scatter/ScatterPoint.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { HoverStyle, LabelStyle, Point } from '..';
+import type { Point2D } from '../../math';
+import type { PointStyle } from '../core/types';
+import type { SVGAttributes } from 'svelte/elements';
+import { type TweenOptions } from 'svelte/motion';
+type $$ComponentProps = Omit<SVGAttributes<SVGGElement>, `style` | `offset` | `origin` | `transform`> & {
+    x: number;
+    y: number;
+    style?: PointStyle;
+    hover?: HoverStyle;
+    label?: LabelStyle;
+    offset?: Point[`offset`];
+    point_tween?: TweenOptions<Point2D>;
+    origin?: Point2D;
+    is_hovered?: boolean;
+    is_selected?: boolean;
+    is_dimmed?: boolean;
+    leader_line_threshold?: number;
+};
+declare const ScatterPoint: import("svelte").Component<$$ComponentProps, {}, "origin" | "point_tween">;
+type ScatterPoint = ReturnType<typeof ScatterPoint>;
+export default ScatterPoint;