ml-time-graph 1.0.0 → 1.0.2

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-CkEYYdSw.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, A as AggregatedPoint, O as HatchVariant, G as FillSpec, a as AggregatedSeries, k as DataPoint, af as TimeSeries } from './scale-O3OLrmn5.js';
+export { b as AggregationConfig, c as AggregationMode, f as AnnotationBandItem, 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, _ as PointStyleType, a2 as SensorType, a3 as SeriesOverlay, a4 as SeriesOverlayKind, a5 as SeriesStyle, a6 as SeriesType, a7 as ShadowStyle, ab as ThresholdLabelConfig, ac as ThresholdLabelPosition } from './scale-O3OLrmn5.js';
 
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
@@ -298,14 +297,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 +354,100 @@ 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` to auto-detect from the
+     *                target's `clientWidth` in {@link mount}.
+     * @param height  Chart height in px.
+     */
+    constructor(width: number, height: number);
+    /** Override the chart's pixel dimensions after construction. */
+    setSize(width: number, height: number): this;
+    /** Override per-side pixel margins. */
+    setMargin(margin: Margin): 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;
+    /** Show / position / orient the integrated legend. */
+    setLegend(legend: LegendOptions): 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;
+}
+
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
  * MIT with Attribution: free use incl. commercial requires visible credit to
@@ -395,6 +490,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 +613,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, AnnotationBandConfig, AnySeries, type AxesConfig, type AxisLabelsStyle, type AxisStyle, DataPoint, type FillBetweenThresholdsInput, FillSpec, Gap, GapsConfig, GraphBuilder, type GridLineStyle, type GridStyle, HatchVariant, Highlight, type LegendOptions, type LegendPosition, type LimitStatsPoint, MLTimeGraph, type MLTimeGraphOptions, type Margin, Marker, type MktPoint, SVGRenderer, type StatsAggregatedPoint, type StdDevPoint, type Theme, Threshold, type TickConfig, TimeSeries, type TooltipOptions, type TooltipSample, type XAxisConfig, type YAxisConfig, attachTooltip, fillBetweenThresholds, getDefaultTheme, mount, parseAggregated, parseDataPoint, parseSeries, resetDefaultTheme, setDefaultTheme };