ml-time-graph 1.0.0 → 1.0.5

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-import { e as LegendOrientation, f as Renderer, M as Marker, d as LegendItem, b as LayoutResult, R as RenderOutput, t as theme } from './layout-Sc5UkC0r.js';
-import { V as LineVariant, h as AnySeries, ab as Threshold, Q as Highlight, J as Gap, O as GapsConfig, e as Annotation, f as AnnotationBandConfig, p as DrawCommand, ae as TimeScale, W as LinearScale, P as HatchVariant, H as FillSpec, a as AggregatedSeries, l as DataPoint, ag as TimeSeries } from './scale-Cbr0KpPz.js';
-export { A as AggregatedPoint, b as AggregationConfig, c as AggregationMode, g as AnnotationBandItem, m as DataPointRef, E as EnumMap, F as FillBound, y as FillDirectionType, z as FillRegion, G as FillSide, I as FillStyle, K as GapConfig, L as GapLabel, M as GapRegion, N as GapStyle, S as LineDashStyle, U as LineStyle, Y as MarkerStyle, $ as PointStyleType, a3 as SensorType, a4 as SeriesOverlay, a5 as SeriesOverlayKind, a6 as SeriesStyle, a7 as SeriesType, a8 as ShadowStyle, ac as ThresholdLabelConfig, ad as ThresholdLabelPosition } from './scale-Cbr0KpPz.js';
-export { L as LimitStatsPoint, M as MktPoint, S as StatsAggregatedPoint, a as StdDevPoint } from './aggregated_subtypes-DZNZyFTX.js';
+import { e as LegendOrientation, f as Renderer, M as Marker, d as LegendItem, b as LayoutResult, R as RenderOutput, t as theme } from './layout-BOYtrsZa.js';
+import { U as LineVariant, g as AnySeries, aa as Threshold, P as Highlight, I as Gap, N as GapsConfig, d as Annotation, e as AnnotationBandConfig, o as DrawCommand, ad as TimeScale, V as LinearScale, O as HatchVariant, f as AnnotationBandItem, _ as PointStyleType, ac as ThresholdLabelPosition, a5 as SeriesStyle, G as FillSpec, af as TimeSeries, A as AggregatedPoint, a as AggregatedSeries, k as DataPoint } from './scale-BRE_QhbZ.js';
+export { b as AggregationConfig, c as AggregationMode, l as DataPointRef, E as EnumMap, F as FillBound, x as FillDirectionType, y as FillRegion, z as FillSide, H as FillStyle, J as GapConfig, K as GapLabel, L as GapRegion, M as GapStyle, R as LineDashStyle, T as LineStyle, X as MarkerStyle, a2 as SensorType, a3 as SeriesOverlay, a4 as SeriesOverlayKind, a6 as SeriesType, a7 as ShadowStyle, ab as ThresholdLabelConfig } from './scale-BRE_QhbZ.js';
 
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
@@ -46,6 +45,8 @@ interface AxisLabelsStyle {
 }
 /** Configuration for one Y-axis (left or right). */
 interface YAxisConfig {
+    /** Position is 'left' or 'right' to determine placement side. Defaults to 'left'. */
+    position?: "left" | "right";
     /** Rotated label drawn next to the axis. */
     label?: string;
     /** Override the value domain. `'auto'` lets the chart compute it from data. */
@@ -86,6 +87,8 @@ interface AxesConfig {
     x?: XAxisConfig;
     left?: YAxisConfig;
     right?: YAxisConfig;
+    /** Y specifies an arbitrary number of vertical axes, each mapped by its slice index. */
+    y?: YAxisConfig[];
 }
 
 /*!
@@ -298,14 +301,16 @@ interface TooltipOptions {
  *   position: absolute;
  *   pointer-events: none;
  *   padding: 6px 10px;
- *   background: rgba(15, 23, 42, 0.92);
- *   color: #fff;
+ *   background: rgba(254, 243, 199, 0.92);  / * sticky-note yellow * /
+ *   color: #1e293b;
+ *   border: 1px solid rgba(217, 119, 6, 0.35);
  *   border-radius: 4px;
  *   font-size: 12px;
  *   transform: translate(8px, 8px);
+ *   box-shadow: 0 2px 6px rgba(0, 0, 0, 0.08);
  * }
- * .mlc-tooltip__time { opacity: 0.7; margin-bottom: 4px; }
- * .mlc-tooltip__name { opacity: 0.8; }
+ * .mlc-tooltip__time { opacity: 0.7; margin-bottom: 4px; font-weight: 600; }
+ * .mlc-tooltip__name { opacity: 0.85; }
  * ```
  */
 declare function attachTooltip(target: HTMLElement, chart: MLTimeGraph, options?: TooltipOptions): () => void;
@@ -353,6 +358,298 @@ interface MountOptions extends MLTimeGraphOptions {
  */
 declare function mount(target: HTMLElement | string, options?: MountOptions): MLTimeGraph;
 
+/*!
+ * 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.
+ */
+
+/**
+ * Imperative builder for MLTimeGraph. Accumulate config via `setX` /
+ * `addX` methods, then materialise via `getSvg()` / `mount()` / `build()`.
+ */
+declare class GraphBuilder {
+    private _opts;
+    private _series;
+    private _thresholds;
+    private _annotations;
+    private _highlights;
+    private _markers;
+    private _bands;
+    private _tooltip?;
+    /**
+     * @param width   Chart width in px. Pass `0` or omit to auto-detect from the
+     *                target's `clientWidth` in {@link mount}.
+     * @param height  Chart height in px.
+     */
+    constructor(width?: number, height?: number);
+    /** Set the chart's pixel width. */
+    setWidth(width: number): this;
+    /** Set the chart's pixel height. */
+    setHeight(height: number): this;
+    /** Override the chart's pixel dimensions. */
+    setSize(width: number, height: number): this;
+    /**
+     * Override per-side pixel margins.
+     * Can be passed as a full `Margin` object or four number arguments: `top, right, bottom, left`.
+     */
+    setMargin(margin: Margin): this;
+    setMargin(top: number, right: number, bottom: number, left: number): this;
+    /** Locale for date/number formatting (e.g. 'de-DE'). */
+    setLocale(locale: string): this;
+    /** Set the entire axes block (x / left / right). Replaces previous. */
+    setAxes(axes: AxesConfig): this;
+    /** Patch just the X-axis config; leaves left/right untouched. */
+    setXAxis(config: XAxisConfig): this;
+    /** Patch just the left Y-axis. */
+    setLeftAxis(config: YAxisConfig): this;
+    /** Patch just the right Y-axis (`yAxisIndex: 1` series). */
+    setRightAxis(config: YAxisConfig): this;
+    /** Patch a specific Y-axis configuration by index. */
+    setYAxis(index: number, config: YAxisConfig): this;
+    /**
+     * Show / position / orient the integrated legend.
+     * Can be passed as a full `LegendOptions` object or three arguments: `show, position, orientation`.
+     */
+    setLegend(legend: LegendOptions): this;
+    setLegend(show: boolean, position?: LegendPosition, orientation?: LegendOrientation): this;
+    /**
+     * Configure data-gap handling. Accepts either the legacy `Gap[]` or the
+     * new `GapsConfig` (`{ regions?, autoDetect?, minGapMs?, style? }`).
+     */
+    setGaps(gaps: Gap[] | GapsConfig): this;
+    /**
+     * Tooltip config. Only takes effect when {@link mount} is used — pure
+     * `getSvg()` output has nothing to hover over. Default `show: true`
+     * when called; pass an explicit `show: false` to keep the chart but
+     * skip the listener.
+     */
+    setTooltip(tooltip: TooltipOptions & {
+        show?: boolean;
+    }): this;
+    /** Append one series. */
+    addSeries(series: AnySeries): this;
+    /** Append multiple series at once. */
+    addSeriesAll(series: AnySeries[]): this;
+    /** Append one threshold (line + optional fill + label). */
+    addThreshold(threshold: Threshold): this;
+    /** Append multiple thresholds at once. */
+    addThresholds(thresholds: Threshold[]): this;
+    /** Append one annotation (line / arrow / rect / point / label). */
+    addAnnotation(annotation: Annotation): this;
+    /** Append multiple annotations at once. */
+    addAnnotations(annotations: Annotation[]): this;
+    /** Append one highlight (coloured time range behind the data). */
+    addHighlight(highlight: Highlight): this;
+    /** Append one marker (vertical pin at a timestamp). */
+    addMarker(marker: Marker): this;
+    /** Append one annotation band (horizontal strip below the chart). */
+    addAnnotationBand(band: AnnotationBandConfig): this;
+    /** Wipe a category of added items. Useful for re-building part of a chart. */
+    clear(category?: "series" | "thresholds" | "annotations" | "highlights" | "markers" | "bands"): this;
+    /** Compose the final MLTimeGraphOptions from current state. */
+    toOptions(): MLTimeGraphOptions;
+    /** Build the chart instance. Each call returns a fresh MLTimeGraph. */
+    build(): MLTimeGraph;
+    /**
+     * Render the chart and return the full `<svg ...>` string. Suitable for
+     * SSR (`fs.writeFileSync(...)`, response body) or for stamping into a
+     * DOM element via `el.innerHTML = builder.getSvg()`.
+     */
+    getSvg(): string;
+    /**
+     * Build the chart AND inject the SVG into a DOM element. Mirrors what
+     * `mount(target, options)` does for the imperative case. Returns the
+     * MLTimeGraph instance so the caller can do further work (tooltips,
+     * setData, etc.).
+     */
+    mount(target: HTMLElement | string): MLTimeGraph;
+}
+/**
+ * TimeSeriesBuilder simplifies constructing raw TimeSeries datasets.
+ */
+declare class TimeSeriesBuilder {
+    private _series;
+    constructor(name: string);
+    /** Appends a value-point to the series. */
+    addPoint(time: number, value: number | null): this;
+    /** Appends an array of data points directly to the series. */
+    addPoints(points: Array<{
+        time: number;
+        value: number | null;
+    }>): this;
+    /** Appends parallel arrays of timestamps and values to the series. */
+    addFloats(times: number[], values: Array<number | null>): this;
+    /** Appends a null point (signaling gaps/offline state). */
+    addNullPoint(time: number): this;
+    /** Assigns the visual styles configuration. */
+    setStyle(style: SeriesStyle): this;
+    /** Shortcut to apply custom stroke styling (color, width, dash style). */
+    setLineStyle(color: string, width: number, style?: LineVariant): this;
+    /** Configures spline interpolation (smoothing) on the series path. */
+    setSmoothing(smooth: boolean): this;
+    /** Assigns the area fill specification. */
+    setFill(fill: FillSpec): this;
+    /** Sets a custom identifier for the series path. */
+    setID(id: string): this;
+    /** Sets named thresholds to split and color the line segment. */
+    setColorByThresholds(thresholdNames: string[]): this;
+    /** Compiles and returns the TimeSeries object. */
+    build(): TimeSeries;
+}
+/**
+ * ThresholdBuilder simplifies constructing value boundaries.
+ */
+declare class ThresholdBuilder {
+    private _threshold;
+    constructor(name: string, value: number);
+    /** Sets the threshold boundary color. */
+    setColor(color: string): this;
+    /** Configures the line type (solid, dashed, dotted, none). */
+    setLine(style: "solid" | "dashed" | "dotted" | "none"): this;
+    /** Configures half-plane fills (above, below, none) and opacity. */
+    setFill(fillType: "above" | "below" | "none", opacity: number): this;
+    /** Configures a hatch pattern style for the fill. */
+    setFillHatch(hatch: HatchVariant): this;
+    /** Configures the labels parameters. */
+    setLabel(text: string, position?: ThresholdLabelPosition): this;
+    /** Configures a unique ID for referencing the threshold. */
+    setID(id: string): this;
+    /** Compiles and returns the Threshold object. */
+    build(): Threshold;
+}
+/**
+ * MarkerBuilder simplifies constructing vertical pins/markers.
+ */
+declare class MarkerBuilder {
+    private _marker;
+    constructor(time: number);
+    /** Sets the marker value (for point markers). */
+    setValue(v: number): this;
+    /** Sets the text label. */
+    setLabel(lbl: string): this;
+    /** Sets the marker color. */
+    setColor(color: string): this;
+    /** Sets the shape of the point marker (circle, square, cross, star, arrow, none). */
+    setPointStyle(style: PointStyleType): this;
+    /** Sets the type of vertical projection line (full, to-value, to-top, none). */
+    setLineStyle(style: "full" | "to-value" | "to-top" | "none"): this;
+    /** Targets a specific series by index for interpolation. */
+    setSeriesIndex(idx: number): this;
+    /** Compiles and returns the Marker object. */
+    build(): Marker;
+}
+/**
+ * HighlightBuilder simplifies constructing highlighted time bands.
+ */
+declare class HighlightBuilder {
+    private _highlight;
+    constructor(startTime: number, endTime: number);
+    /** Sets the text label. */
+    setLabel(lbl: string): this;
+    /** Sets the background color. */
+    setColor(color: string): this;
+    /** Sets the opacity. */
+    setOpacity(opacity: number): this;
+    /** Sets the label alignment (top, center, bottom, above, below). */
+    setLabelPosition(pos: "top" | "center" | "bottom" | "above" | "below"): this;
+    /** Sets the text rotation in degrees. */
+    setRotate(rotate: number): this;
+    /** Compiles and returns the Highlight object. */
+    build(): Highlight;
+}
+/**
+ * AnnotationBuilder simplifies constructing free-form annotations.
+ */
+declare class AnnotationBuilder {
+    private _ann;
+    constructor(typ: "line" | "arrow" | "rect" | "point" | "label");
+    /** Sets a unique identifier. */
+    setID(id: string): this;
+    /** Sets the title (used for legend / toggles, not drawn). */
+    setTitle(title: string): this;
+    /** Sets the start point coordinate reference. */
+    setFrom(time: number, value: number, axis?: number): this;
+    /** Sets the end point coordinate reference. */
+    setTo(time: number, value: number, axis?: number): this;
+    /** Sets the coordinate reference position (for point/label). */
+    setAt(time: number, value: number, axis?: number): this;
+    /** Sets the primary stroke/text color. */
+    setColor(color: string): this;
+    /** Sets the stroke width. */
+    setWidth(w: number): this;
+    /** Sets the dash pattern ("dashed" | "dotted"). */
+    setDash(dash: "dashed" | "dotted"): this;
+    /** Sets the arrowhead size (arrow only). */
+    setHeadSize(size: number): this;
+    /** Sets the fill color. */
+    setFill(fill: string): this;
+    /** Sets the hatch pattern variant. */
+    setHatch(hatch: HatchVariant): this;
+    /** Sets the stroke color. */
+    setStroke(stroke: string): this;
+    /** Sets the opacity. */
+    setOpacity(opacity: number): this;
+    /** Sets the point radius (point only). */
+    setRadius(radius: number): this;
+    /** Sets the point shape (point only). */
+    setShape(shape: "circle" | "square" | "cross"): this;
+    /** Sets the label text (label only). */
+    setText(text: string): this;
+    /** Sets the text anchor (label only). */
+    setAnchor(anchor: "start" | "middle" | "end"): this;
+    /** Sets the horizontal offset (label only). */
+    setDx(dx: number): this;
+    /** Sets the vertical offset (label only). */
+    setDy(dy: number): this;
+    /** Sets the label rotation in degrees (label only). */
+    setRotate(rotate: number): this;
+    /** Compiles and returns the Annotation object. */
+    build(): Annotation;
+}
+/**
+ * AnnotationBandBuilder simplifies constructing annotation bands below the chart.
+ */
+declare class AnnotationBandBuilder {
+    private _band;
+    constructor(name: string);
+    /** Sets the band height in pixels. */
+    setHeight(h: number): this;
+    /** Sets the vertical spacing between bands. */
+    setSpacing(s: number): this;
+    /** Sets a default hatch pattern variant for all items in the band. */
+    setHatch(hatch: HatchVariant): this;
+    /** Sets whether to draw a time axis under the band. */
+    setShowAxis(show: boolean): this;
+    /** Sets whether the band is listed in the chart legend. */
+    setShowInLegend(show: boolean): this;
+    /** Sets the background color of the band. */
+    setBackground(bg: string): this;
+    /** Adds an event range/item to the band. */
+    addItem(item: AnnotationBandItem): this;
+    /** Compiles and returns the AnnotationBandConfig object. */
+    build(): AnnotationBandConfig;
+}
+/**
+ * AnnotationBandItemBuilder simplifies constructing annotation band event ranges.
+ */
+declare class AnnotationBandItemBuilder {
+    private _item;
+    constructor(startTime: number, endTime: number);
+    /** Sets the fill color. */
+    setFill(fill: string): this;
+    /** Sets the hatch pattern variant. */
+    setHatch(hatch: HatchVariant): this;
+    /** Sets the border stroke color. */
+    setStroke(stroke: string): this;
+    /** Sets the border stroke width. */
+    setStrokeWidth(w: number): this;
+    /** Sets the text label and optional label formatting fields. */
+    setLabel(lbl: string, fontSize?: number, fill?: string, baseline?: 'top' | 'middle' | 'bottom'): this;
+    /** Compiles and returns the AnnotationBandItem object. */
+    build(): AnnotationBandItem;
+}
+
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
  * MIT with Attribution: free use incl. commercial requires visible credit to
@@ -395,6 +692,46 @@ declare class SVGRenderer extends Renderer {
     _esc(s: string): string;
 }
 
+/*!
+ * 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.
+ */
+
+/** Slot carrying a rolling Mean Kinetic Temperature value (USP <1079.2>). */
+interface MktPoint extends AggregatedPoint {
+    /** Mean kinetic temperature for this slot. `null` = gap. */
+    mkt: number | null;
+    /** Delta vs the previous slot's MKT (optional). */
+    deltaMkt?: number | null;
+}
+/** Slot carrying the standard deviation of the samples in the window. */
+interface StdDevPoint extends AggregatedPoint {
+    /** Standard deviation of the samples in this slot. `null` = gap. */
+    stdDev: number | null;
+}
+/**
+ * Slot carrying minutes-above-/below-limit statistics. At least one of
+ * `minutesAboveHigh` or `minutesBelowLow` must be set.
+ */
+interface LimitStatsPoint extends AggregatedPoint {
+    /** Minutes above the upper limit in this slot. */
+    minutesAboveHigh?: number | null;
+    /** Minutes below the lower limit in this slot. */
+    minutesBelowLow?: number | null;
+}
+/**
+ * The "full-stats" aggregated slot — combines all three specialised
+ * subtypes via intersection. This is what `aggregateBySlot(data, mode,
+ * thresholds)` returns when thresholds are provided: per-slot MKT (USP
+ * <1079.2>), standard deviation, and out-of-bounds minute counters.
+ *
+ * Prefer this typed alias over plain `AggregatedPoint` whenever you
+ * downstream-consume `aggregateBySlot`'s output and want guaranteed access
+ * to the stat fields.
+ */
+type StatsAggregatedPoint = MktPoint & StdDevPoint & LimitStatsPoint;
+
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
  * MIT with Attribution: free use incl. commercial requires visible credit to
@@ -478,4 +815,4 @@ declare function getDefaultTheme(): Readonly<Theme>;
  */
 declare function resetDefaultTheme(): void;
 
-export { AggregatedSeries, Annotation, AnnotationBandConfig, AnySeries, type AxesConfig, type AxisLabelsStyle, type AxisStyle, DataPoint, type FillBetweenThresholdsInput, FillSpec, Gap, GapsConfig, type GridLineStyle, type GridStyle, HatchVariant, Highlight, type LegendOptions, type LegendPosition, MLTimeGraph, type MLTimeGraphOptions, type Margin, Marker, SVGRenderer, type Theme, Threshold, type TickConfig, TimeSeries, type TooltipOptions, type TooltipSample, type XAxisConfig, type YAxisConfig, attachTooltip, fillBetweenThresholds, getDefaultTheme, mount, parseAggregated, parseDataPoint, parseSeries, resetDefaultTheme, setDefaultTheme };
+export { AggregatedPoint, AggregatedSeries, Annotation, AnnotationBandBuilder, AnnotationBandConfig, AnnotationBandItem, AnnotationBandItemBuilder, AnnotationBuilder, AnySeries, type AxesConfig, type AxisLabelsStyle, type AxisStyle, DataPoint, type FillBetweenThresholdsInput, FillSpec, Gap, GapsConfig, GraphBuilder, type GridLineStyle, type GridStyle, HatchVariant, Highlight, HighlightBuilder, type LegendOptions, type LegendPosition, type LimitStatsPoint, MLTimeGraph, type MLTimeGraphOptions, type Margin, Marker, MarkerBuilder, type MktPoint, PointStyleType, SVGRenderer, SeriesStyle, type StatsAggregatedPoint, type StdDevPoint, type Theme, Threshold, ThresholdBuilder, ThresholdLabelPosition, type TickConfig, TimeSeries, TimeSeriesBuilder, type TooltipOptions, type TooltipSample, type XAxisConfig, type YAxisConfig, attachTooltip, fillBetweenThresholds, getDefaultTheme, mount, parseAggregated, parseDataPoint, parseSeries, resetDefaultTheme, setDefaultTheme };