ml-time-graph 1.0.0

package/dist/interaction/index.d.ts

@@ -0,0 +1,141 @@
+import { l as DataPoint, p as DrawCommand, ae as TimeScale, W as LinearScale } from '../scale-Cbr0KpPz.js';
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+/** Configuration for zoom behavior (speed, min/max domain). */
+interface ZoomConfig {
+    /** Enable or disable zoom interaction (default true). */
+    enabled?: boolean;
+    /** Zoom speed factor per wheel event (default 0.1). */
+    zoomSpeed?: number;
+    /** Minimum time span in ms before zoom stops (default 0). */
+    minDomainMs?: number;
+    /** Maximum time span in ms (default 365 days). */
+    maxDomainMs?: number;
+}
+/** Current zoom state including zoomed domain, scale factor, and offset. */
+interface ZoomState {
+    domain: [number, number];
+    originalDomain: [number, number];
+    scale: number;
+    offset: number;
+}
+/** Handles mouse/trackpad zoom and pan, with clamping to original data domain. */
+declare class Zoom {
+    private readonly _config;
+    private _state;
+    constructor(initialDomain: [number, number], config?: ZoomConfig);
+    get state(): ZoomState;
+    applyZoom(x: number, delta: number, rangeWidth: number): void;
+    applyPan(pixelDelta: number, rangeWidth: number): void;
+    reset(): void;
+    get enabled(): boolean;
+}
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Configuration for minimap overview (thumbnail chart with viewport indicator). */
+interface MinimapConfig {
+    /** Data points for overview */
+    data: DataPoint[];
+    /** Minimap dimensions */
+    width: number;
+    height: number;
+    /** Position */
+    x: number;
+    y: number;
+    /** Zoom state for brush indicator */
+    zoom?: Zoom;
+    /** Line color */
+    stroke?: string;
+    /** Background color */
+    bgColor?: string;
+    /** Brush (viewport) color */
+    brushColor?: string;
+}
+/** Renders a minimap (thumbnail overview) with an optional brush indicator showing the current viewport. */
+declare class Minimap {
+    private readonly _data;
+    private readonly _width;
+    private readonly _height;
+    private readonly _x;
+    private readonly _y;
+    private readonly _zoom?;
+    private readonly _stroke;
+    private readonly _bgColor;
+    private readonly _brushColor;
+    constructor(config: MinimapConfig);
+    /** Render minimap as draw commands */
+    render(): DrawCommand[];
+    /** Convert minimap pixel X to time value (for click-to-navigate) */
+    navigateTo(pixelX: number): number;
+}
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Configuration for tooltip rendering (crosshair, data snap, and value display). */
+interface TooltipConfig {
+    /** X position in pixels */
+    mouseX: number;
+    /** Y position in pixels */
+    mouseY: number;
+    /** Time scale */
+    timeScale: TimeScale;
+    /** Value scale */
+    valueScale: LinearScale;
+    /** Data points */
+    data: DataPoint[];
+    /** X range of the chart */
+    xRange: [number, number];
+    /** Y range of the chart */
+    yRange: [number, number];
+    /** Maximum snap distance in pixels */
+    snapRadius?: number;
+    /** Tooltip background */
+    bgColor?: string;
+    /** Tooltip border */
+    borderColor?: string;
+    /** Label color */
+    textColor?: string;
+}
+/** Tooltip result containing visibility state, render commands, and snapped data point. */
+interface TooltipResult {
+    /** Whether tooltip should be shown */
+    visible: boolean;
+    /** Commands to render the tooltip */
+    commands: DrawCommand[];
+    /** Closest data point (if any) */
+    dataPoint?: DataPoint;
+    /** Snapped pixel X position */
+    snapX?: number;
+}
+/** Computes tooltip visibility and renders crosshair + value box at the nearest data point. */
+declare class Tooltip {
+    private readonly _mouseX;
+    private readonly _mouseY;
+    private readonly _timeScale;
+    private readonly _valueScale;
+    private readonly _data;
+    private readonly _xRange;
+    private readonly _yRange;
+    private readonly _snapRadius;
+    private readonly _bgColor;
+    private readonly _borderColor;
+    private readonly _textColor;
+    constructor(config: TooltipConfig);
+    /** Compute tooltip visibility and render commands */
+    compute(): TooltipResult;
+}
+
+export { Minimap, type MinimapConfig, Tooltip, type TooltipConfig, type TooltipResult, Zoom, type ZoomConfig, type ZoomState };

package/dist/interaction/index.js

@@ -0,0 +1,438 @@
+// src/core/scale.ts
+var LinearScale = class {
+  #domain;
+  #range;
+  constructor(config) {
+    this.#domain = [...config.domain];
+    this.#range = [...config.range];
+  }
+  map(value) {
+    const v = Number(value);
+    const [d0, d1] = this.#domain;
+    const [r0, r1] = this.#range;
+    if (d1 === d0) return r0;
+    return r0 + (v - d0) / (d1 - d0) * (r1 - r0);
+  }
+  invert(pixel) {
+    const [d0, d1] = this.#domain;
+    const [r0, r1] = this.#range;
+    if (r1 === r0) return d0;
+    return d0 + (pixel - r0) / (r1 - r0) * (d1 - d0);
+  }
+  domain() {
+    return [...this.#domain];
+  }
+  range() {
+    return [...this.#range];
+  }
+};
+var TIME_INTERVALS = [
+  { label: "second", ms: 1e3 },
+  { label: "2_seconds", ms: 2e3 },
+  { label: "5_seconds", ms: 5e3 },
+  { label: "10_seconds", ms: 1e4 },
+  { label: "30_seconds", ms: 3e4 },
+  { label: "minute", ms: 6e4 },
+  { label: "5_minutes", ms: 3e5 },
+  { label: "15_minutes", ms: 9e5 },
+  { label: "30_minutes", ms: 18e5 },
+  { label: "hour", ms: 36e5 },
+  { label: "3_hours", ms: 108e5 },
+  { label: "6_hours", ms: 216e5 },
+  { label: "day", ms: 864e5 },
+  { label: "week", ms: 6048e5 },
+  { label: "month", ms: 2592e6 },
+  { label: "3_months", ms: 7776e6 },
+  { label: "6_months", ms: 15552e6 },
+  { label: "year", ms: 31536e6 },
+  { label: "2_years", ms: 63072e6 },
+  { label: "5_years", ms: 15768e7 }
+];
+var TimeScale = class {
+  #linear;
+  #locale;
+  constructor(config) {
+    this.#linear = new LinearScale({
+      domain: config.domain,
+      range: config.range
+    });
+    this.#locale = config.locale || (typeof navigator !== "undefined" ? navigator.language : "en-US");
+  }
+  map(value) {
+    return this.#linear.map(Number(value));
+  }
+  invert(pixel) {
+    return this.#linear.invert(pixel);
+  }
+  domain() {
+    return this.#linear.domain();
+  }
+  range() {
+    return this.#linear.range();
+  }
+  get locale() {
+    return this.#locale;
+  }
+  /**
+   * Pick the "nicest" time interval that yields roughly `targetTicks` ticks
+   * across the visible range. Clamps to minTicks / maxTicks bounds.
+   */
+  tickInterval(targetTicks, minTicks = 3, maxTicks = 12) {
+    const [d0, d1] = this.#linear.domain();
+    const totalMs = d1 - d0;
+    if (totalMs <= 0) return { interval: TIME_INTERVALS[0].ms };
+    const ideal = totalMs / targetTicks;
+    let picked = TIME_INTERVALS[0].ms;
+    for (const t of TIME_INTERVALS) {
+      if (t.ms >= ideal) {
+        picked = t.ms;
+        break;
+      }
+    }
+    let candidate = picked;
+    let count = Math.round(totalMs / candidate);
+    while (count > maxTicks && candidate < TIME_INTERVALS[TIME_INTERVALS.length - 1].ms) {
+      const idx = TIME_INTERVALS.findIndex((t) => t.ms === candidate);
+      candidate = TIME_INTERVALS[Math.min(idx + 1, TIME_INTERVALS.length - 1)].ms;
+      count = Math.round(totalMs / candidate);
+    }
+    while (count < minTicks && candidate > TIME_INTERVALS[0].ms) {
+      const idx = TIME_INTERVALS.findIndex((t) => t.ms === candidate);
+      candidate = TIME_INTERVALS[Math.max(idx - 1, 0)].ms;
+      count = Math.round(totalMs / candidate);
+    }
+    return { interval: candidate };
+  }
+  /**
+   * Generate tick positions (timestamps) across the domain.
+   */
+  ticks(opts) {
+    const minT = opts?.minTicks ?? 5;
+    const maxT = opts?.maxTicks ?? 12;
+    const { interval } = this.tickInterval(
+      (minT + maxT) / 2,
+      minT,
+      maxT
+    );
+    const [d0, d1] = this.#linear.domain();
+    const result = [];
+    const start = Math.ceil(d0 / interval) * interval;
+    for (let t = start; t <= d1; t += interval) {
+      result.push(t);
+    }
+    return result;
+  }
+  /** Format a timestamp using Intl.DateTimeFormat */
+  format(timestamp, formatOpts) {
+    return new Intl.DateTimeFormat(this.#locale, formatOpts).format(
+      new Date(timestamp)
+    );
+  }
+};
+
+// src/interaction/zoom.ts
+var Zoom = class {
+  _config;
+  _state;
+  constructor(initialDomain, config) {
+    this._config = {
+      enabled: config?.enabled ?? true,
+      zoomSpeed: config?.zoomSpeed ?? 0.1,
+      minDomainMs: config?.minDomainMs ?? 0,
+      maxDomainMs: config?.maxDomainMs ?? 365 * 24 * 60 * 60 * 1e3
+    };
+    this._state = {
+      domain: [...initialDomain],
+      originalDomain: [...initialDomain],
+      scale: 1,
+      offset: 0
+    };
+  }
+  get state() {
+    return { ...this._state, domain: [...this._state.domain] };
+  }
+  applyZoom(x, delta, rangeWidth) {
+    if (!this._config.enabled) return;
+    const factor = 1 + Math.sign(delta) * this._config.zoomSpeed;
+    if (factor <= 0) return;
+    const [d0, d1] = this._state.domain;
+    const span = d1 - d0;
+    const ratio = x / rangeWidth;
+    let newSpan = span / factor;
+    const minSpan = this._config.minDomainMs ?? 0;
+    const maxSpan = this._config.maxDomainMs ?? Infinity;
+    if (newSpan < minSpan) newSpan = minSpan;
+    if (newSpan > maxSpan) newSpan = maxSpan;
+    const focalPoint = d0 + span * ratio;
+    let newD0 = focalPoint - newSpan * ratio;
+    let newD1 = focalPoint + newSpan * (1 - ratio);
+    const [orig0, orig1] = this._state.originalDomain;
+    if (newD1 - newD0 > orig1 - orig0) {
+      newD0 = orig0;
+      newD1 = orig1;
+      newSpan = orig1 - orig0;
+    } else {
+      if (newD0 < orig0) {
+        newD1 = orig1 - (orig1 - orig0) * ((newD1 - newD0) / (orig1 - orig0));
+        newD0 = orig0;
+      }
+      if (newD1 > orig1) {
+        newD0 = orig0 + (orig1 - orig0) * ((newD0 - orig0) / (orig1 - orig0));
+        newD1 = orig1;
+      }
+    }
+    this._state.domain = [newD0, newD1];
+    this._state.scale = (d1 - d0) / newSpan;
+  }
+  applyPan(pixelDelta, rangeWidth) {
+    if (!this._config.enabled) return;
+    const [d0, d1] = this._state.domain;
+    const span = d1 - d0;
+    const [orig0, orig1] = this._state.originalDomain;
+    let shift = -(pixelDelta / rangeWidth) * span;
+    let newD0 = d0 + shift;
+    let newD1 = d1 + shift;
+    if (newD0 < orig0) {
+      shift -= newD0 - orig0;
+    }
+    if (newD1 > orig1) {
+      shift -= newD1 - orig1;
+    }
+    this._state.domain = [d0 + shift, d1 + shift];
+  }
+  reset() {
+    this._state.domain = [...this._state.originalDomain];
+    this._state.scale = 1;
+    this._state.offset = 0;
+  }
+  get enabled() {
+    return this._config.enabled ?? true;
+  }
+};
+
+// src/theme/defaults.ts
+var theme = {
+  // ── Tooltip ──
+  /** Tooltip box background */
+  tooltipBg: "#fff",
+  /** Tooltip border */
+  tooltipBorder: "#cbd5e1",
+  /** Tooltip text color */
+  tooltipText: "#1e293b",
+  /** Tooltip snap radius in pixels */
+  tooltipSnapRadius: 20,
+  // ── Minimap ──
+  /** Minimap overview line stroke */
+  minimapStroke: "#94a3b8",
+  /** Minimap background */
+  minimapBg: "#f8f9fa",
+  /** Minimap brush (viewport) fill */
+  minimapBrush: "#3b82f644"};
+
+// src/interaction/minimap.ts
+var Minimap = class {
+  _data;
+  _width;
+  _height;
+  _x;
+  _y;
+  _zoom;
+  _stroke;
+  _bgColor;
+  _brushColor;
+  constructor(config) {
+    this._data = config.data;
+    this._width = config.width;
+    this._height = config.height;
+    this._x = config.x;
+    this._y = config.y;
+    this._zoom = config.zoom;
+    this._stroke = config.stroke ?? theme.minimapStroke;
+    this._bgColor = config.bgColor ?? theme.minimapBg;
+    this._brushColor = config.brushColor ?? theme.minimapBrush;
+  }
+  /** Render minimap as draw commands */
+  render() {
+    if (this._data.length === 0) return [];
+    const commands = [];
+    const times = this._data.map((d) => d.time);
+    const values = this._data.map((d) => d.value).filter((v) => v !== null);
+    const timeDomain = [Math.min(...times), Math.max(...times)];
+    const valueDomain = [Math.min(...values), Math.max(...values)];
+    const timeScale = new TimeScale({
+      domain: timeDomain,
+      range: [0, this._width]
+    });
+    const valueScale = new LinearScale({
+      domain: valueDomain,
+      range: [this._height, 0]
+    });
+    commands.push({
+      type: "rect",
+      x: this._x,
+      y: this._y,
+      w: this._width,
+      h: this._height,
+      fill: this._bgColor
+    });
+    const points = this._data.map((d) => ({
+      x: this._x + timeScale.map(d.time),
+      y: this._y + valueScale.map(d.value)
+    }));
+    commands.push({
+      type: "path",
+      points,
+      smoothing: false,
+      stroke: this._stroke,
+      strokeWidth: 1
+    });
+    if (this._zoom) {
+      const zoomState = this._zoom.state;
+      const brushX0 = this._x + timeScale.map(zoomState.domain[0]);
+      const brushX1 = this._x + timeScale.map(zoomState.domain[1]);
+      const brushW = Math.max(2, brushX1 - brushX0);
+      commands.push({
+        type: "rect",
+        x: brushX0,
+        y: this._y,
+        w: brushW,
+        h: this._height,
+        fill: this._brushColor
+      });
+    }
+    return commands;
+  }
+  /** Convert minimap pixel X to time value (for click-to-navigate) */
+  navigateTo(pixelX) {
+    const times = this._data.map((d) => d.time);
+    const timeDomain = [Math.min(...times), Math.max(...times)];
+    const timeScale = new TimeScale({ domain: timeDomain, range: [0, this._width] });
+    const localX = pixelX - this._x;
+    return timeScale.invert(localX);
+  }
+};
+
+// src/interaction/tooltip.ts
+var Tooltip = class {
+  _mouseX;
+  _mouseY;
+  _timeScale;
+  _valueScale;
+  _data;
+  _xRange;
+  _yRange;
+  _snapRadius;
+  _bgColor;
+  _borderColor;
+  _textColor;
+  constructor(config) {
+    this._mouseX = config.mouseX;
+    this._mouseY = config.mouseY;
+    this._timeScale = config.timeScale;
+    this._valueScale = config.valueScale;
+    this._data = config.data;
+    this._xRange = config.xRange;
+    this._yRange = config.yRange;
+    this._snapRadius = config.snapRadius ?? theme.tooltipSnapRadius;
+    this._bgColor = config.bgColor ?? theme.tooltipBg;
+    this._borderColor = config.borderColor ?? theme.tooltipBorder;
+    this._textColor = config.textColor ?? theme.tooltipText;
+  }
+  /** Compute tooltip visibility and render commands */
+  compute() {
+    this._timeScale.invert(this._mouseX);
+    const sorted = [...this._data].filter((d) => d.value !== null).sort((a, b) => a.time - b.time);
+    let closest;
+    let closestDist = Infinity;
+    for (const dp of sorted) {
+      const px = this._timeScale.map(dp.time);
+      const dist = Math.abs(this._mouseX - px);
+      if (dist < closestDist) {
+        closestDist = dist;
+        closest = dp;
+      }
+    }
+    if (!closest || closestDist > this._snapRadius) {
+      return { visible: false, commands: [] };
+    }
+    const snapX = this._timeScale.map(closest.time);
+    const snapY = this._valueScale.map(closest.value);
+    const commands = [];
+    commands.push({
+      type: "line",
+      x1: snapX,
+      y1: this._yRange[0],
+      x2: snapX,
+      y2: this._yRange[1],
+      stroke: "#94a3b8",
+      strokeWidth: 1
+    });
+    commands.push({
+      type: "line",
+      x1: this._xRange[0],
+      y1: snapY,
+      x2: this._xRange[1],
+      y2: snapY,
+      stroke: "#94a3b8",
+      strokeWidth: 1
+    });
+    commands.push({
+      type: "circle",
+      cx: snapX,
+      cy: snapY,
+      r: 5,
+      fill: "#3b82f6"
+    });
+    const timeLabel = new Date(closest.time).toLocaleString();
+    const valueLabel = closest.value.toFixed(2);
+    const boxW = 120;
+    const boxH = 44;
+    let boxX = snapX + 12;
+    let boxY = snapY - boxH - 4;
+    if (boxX + boxW > this._xRange[1]) {
+      boxX = snapX - boxW - 12;
+    }
+    if (boxY < this._yRange[0]) {
+      boxY = snapY + 12;
+    }
+    commands.push({
+      type: "rect",
+      x: boxX,
+      y: boxY,
+      w: boxW,
+      h: boxH,
+      fill: this._bgColor,
+      stroke: this._borderColor,
+      strokeWidth: 1
+    });
+    commands.push({
+      type: "text",
+      content: timeLabel,
+      x: boxX + 8,
+      y: boxY + 16,
+      fontSize: 10,
+      fill: this._textColor
+    });
+    commands.push({
+      type: "text",
+      content: `Value: ${valueLabel}`,
+      x: boxX + 8,
+      y: boxY + 32,
+      fontSize: 11,
+      fill: "#3b82f6"
+    });
+    return {
+      visible: true,
+      commands,
+      dataPoint: closest,
+      snapX
+    };
+  }
+};
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+export { Minimap, Tooltip, Zoom };