ml-time-graph 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,481 @@
+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';
+
+/*!
+ * 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.
+ */
+
+/** Tick density / sizing for one axis. */
+interface TickConfig {
+    /** Target number of major (labelled) ticks. */
+    major?: number;
+    /** How many minor ticks to place between two major ticks. Default 0 = off. */
+    minor?: number;
+    /** Tick mark length in px. */
+    size?: number;
+}
+/** Grid line styling for one tick level. `false` disables that grid level. */
+interface GridLineStyle {
+    color?: string;
+    width?: number;
+    style?: LineVariant;
+    opacity?: number;
+}
+/**
+ * Per-axis grid configuration. Each tick level (major / minor) can be styled
+ * independently or disabled. Defaults: major grid shown with theme colours,
+ * minor grid off.
+ */
+interface GridStyle {
+    major?: GridLineStyle | false;
+    minor?: GridLineStyle | false;
+}
+/** Axis baseline + tick marks styling. */
+interface AxisStyle {
+    color?: string;
+    width?: number;
+}
+/** Tick / axis-label text styling. */
+interface AxisLabelsStyle {
+    color?: string;
+    fontSize?: number;
+}
+/** Configuration for one Y-axis (left or right). */
+interface YAxisConfig {
+    /** Rotated label drawn next to the axis. */
+    label?: string;
+    /** Override the value domain. `'auto'` lets the chart compute it from data. */
+    domain?: [number, number] | "auto";
+    /** Format a tick value into its label text. */
+    format?: (value: number) => string;
+    /** Tick density / sizing. */
+    ticks?: TickConfig;
+    /** Per-tick-level grid styling. */
+    grid?: GridStyle;
+    /** Axis baseline + tick marks styling. */
+    axis?: AxisStyle;
+    /** Tick label text styling. */
+    labels?: AxisLabelsStyle;
+}
+/** Configuration for the X (time) axis. */
+interface XAxisConfig {
+    /** Label drawn below the axis. */
+    label?: string;
+    /** Override the time domain. `'auto'` lets the chart compute it from data. */
+    domain?: [number, number] | "auto";
+    /** Custom formatter for tick labels (called with a `Date`). */
+    format?: (d: Date) => string;
+    /** Tick density / sizing. */
+    ticks?: TickConfig;
+    /** Per-tick-level grid styling. */
+    grid?: GridStyle;
+    /** Axis baseline + tick marks styling. */
+    axis?: AxisStyle;
+    /** Tick label text styling. */
+    labels?: AxisLabelsStyle;
+}
+/**
+ * Top-level axes container on {@link MLTimeGraphOptions}.
+ * `left` and `right` correspond to `yAxisIndex: 0` and `yAxisIndex: 1` series.
+ */
+interface AxesConfig {
+    x?: XAxisConfig;
+    left?: YAxisConfig;
+    right?: YAxisConfig;
+}
+
+/*!
+ * 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.
+ */
+
+/** Chart margins in pixels. */
+interface Margin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Legend placement position — inside or outside the chart area. */
+type LegendPosition = 'inside-right' | 'inside-left' | 'outside-right' | 'outside-left' | 'separate';
+interface LegendOptions {
+    /** Show the legend (default false). */
+    show?: boolean;
+    /** Placement (default 'inside-right'). 'separate' draws nothing — read chart.legendItems() and render your own. */
+    position?: LegendPosition;
+    /** Item layout direction (default 'vertical'). */
+    orientation?: LegendOrientation;
+}
+interface MLTimeGraphOptions {
+    /** Chart dimensions */
+    width?: number;
+    height?: number;
+    /** Margins */
+    margin?: Margin;
+    /** Renderer (injected) */
+    renderer?: Renderer;
+    /** Time series data (raw or aggregated min/max/avg) */
+    series?: AnySeries[];
+    /** Locale for i18n (e.g. 'de-DE') */
+    locale?: string;
+    /** Integrated legend configuration */
+    legend?: LegendOptions;
+    /** Markers */
+    markers?: Marker[];
+    /** Threshold bands / lines / fills drawn behind the series */
+    thresholds?: Threshold[];
+    /** Highlighted time regions drawn behind the series */
+    highlights?: Highlight[];
+    /**
+     * Data-gap configuration. Two equivalent forms:
+     * - `Gap[]`              — legacy: array of region objects with flat
+     *                          fill/hatch/labelBaseline/rotate fields.
+     * - {@link GapsConfig}   — new (preferred): `{ regions?, autoDetect?,
+     *                          minGapMs?, style? }`, where `style` provides
+     *                          per-region fallbacks and `autoDetect` (TODO)
+     *                          will derive gaps from time spacing in
+     *                          Phase 3+. For now: typed but not yet acted on.
+     */
+    gaps?: Gap[] | GapsConfig;
+    /** Free-form overlays (arrow, line, rect, point, label) in data coordinates */
+    annotations?: Annotation[];
+    /** Horizontal annotation bands below the chart (colored time ranges + labels) */
+    annotationBands?: AnnotationBandConfig[];
+    /**
+     * First-class axes configuration: per-axis `label`, `format`, `ticks`, `grid`,
+     * `axis`, `labels` (see API_DESIGN.md §7).
+     */
+    axes?: AxesConfig;
+}
+
+/*!
+ * 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.
+ */
+
+/**
+ * Time-series chart. Configure it with {@link MLTimeGraphOptions} (series,
+ * thresholds, legend, axis labels, …), then call {@link MLTimeGraph.renderCommands}
+ * to get renderer-agnostic draw commands — a {@link Renderer} (e.g. SVGRenderer)
+ * turns those into output. The chart never touches the DOM itself.
+ */
+declare class MLTimeGraph {
+    private readonly _layout;
+    private readonly _renderer?;
+    private readonly _locale?;
+    private readonly _legend?;
+    private readonly _markers;
+    private readonly _thresholds;
+    private readonly _highlights;
+    private readonly _gaps;
+    private readonly _gapsAutoDetect;
+    private readonly _gapsMinGapMs;
+    private _annotations;
+    private readonly _annotationBands;
+    private readonly _disabledAnnotations;
+    private _annotationSeq;
+    private readonly _axes?;
+    private _series;
+    private _annotationBandHeight;
+    private _timeScale?;
+    private _valueScales;
+    /** @param options Chart configuration; every field is optional and has a sensible default. */
+    constructor(options?: MLTimeGraphOptions);
+    getWidth(): number;
+    getHeight(): number;
+    /** Read-only view of the parsed series array (post-`setData`). */
+    get series(): readonly AnySeries[];
+    _annotationBandTotalHeight(): number;
+    /** Set chart data (raw or aggregated series with a non-empty `data` array). */
+    setData(series: AnySeries[]): void;
+    /** Add a free-form annotation. Returns its id. */
+    addAnnotation(annotation: Annotation): string;
+    /** Remove an annotation by id. */
+    removeAnnotation(id: string): boolean;
+    /** Replace all annotations. */
+    setAnnotations(annotations: Annotation[]): void;
+    /** Remove all annotations. */
+    clearAnnotations(): void;
+    /** Current annotations (read-only snapshot). */
+    getAnnotations(): readonly Annotation[];
+    /** Hide an annotation by id. */
+    disableAnnotation(id: string): void;
+    /** Re-show a previously disabled annotation. */
+    enableAnnotation(id: string): void;
+    private _axisIndexOf;
+    private _timesOf;
+    private _valuesOf;
+    /**
+     * Compute the chart's renderer-agnostic draw commands.
+     */
+    renderCommands(): DrawCommand[];
+    /** Build the draw commands for a single series based on its type. */
+    private _renderSeries;
+    private _interpolateValue;
+    legendItems(): LegendItem[];
+    private _legendItems;
+    get renderer(): Renderer | undefined;
+    get layout(): LayoutResult;
+    get timeScale(): TimeScale | undefined;
+    get valueScales(): Map<number, LinearScale>;
+    invertTime(x: number): number;
+    invertValue(y: number, axisIndex?: number): number;
+    project(time: number, value: number, axisIndex?: number): {
+        x: number;
+        y: 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.
+ */
+
+/** A single sample at the cursor's X position — one per series. */
+interface TooltipSample {
+    /** Index of the series in the chart's `series[]`. */
+    seriesIndex: number;
+    /** The series itself (for `.name`, `.style.line.color`, etc.). */
+    series: AnySeries;
+    /** Timestamp of the closest sample to the cursor (ms). */
+    time: number;
+    /** Numeric value of the sample. For aggregated series this is the `avg`. */
+    value: number;
+    /** Pixel X of the sample in the rendered SVG. */
+    x: number;
+    /** Pixel Y of the sample in the rendered SVG. */
+    y: number;
+}
+/** Configuration for the DOM-attached tooltip helper. */
+interface TooltipOptions {
+    /** Master switch — set to true to enable. Default: false. */
+    show?: boolean;
+    /**
+     * Custom HTML formatter. The argument is one entry per series at the
+     * cursor's X position. Return raw HTML — it goes into the tooltip's
+     * `innerHTML`. If not given, a sensible default is used (time header
+     * + one row per series with `name: value`).
+     */
+    format?: (samples: TooltipSample[]) => string;
+    /**
+     * Maximum cursor-to-sample distance in pixels for a sample to count.
+     * Default: `Infinity` (always snap to the nearest sample of each
+     * series, regardless of distance).
+     */
+    snapRadius?: number;
+    /** CSS class for the tooltip `<div>`. Default: `'mlc-tooltip'`. */
+    className?: string;
+    /**
+     * Highlight each picked sample with a hollow-ring marker in the SVG
+     * (white fill, stroke = series colour). Default: `true`.
+     */
+    showPicks?: boolean;
+    /** Radius (px) for the pick marker. Default: 5. */
+    pickRadius?: number;
+    /** CSS class for the picks-group `<g>`. Default: `'mlc-tooltip-picks'`. */
+    picksClassName?: string;
+}
+/**
+ * Attach an interactive tooltip to a rendered chart. Listens to mousemove
+ * on the chart's `<svg>` element, snaps each series to its nearest sample
+ * at the cursor's X position, and renders the result via the `format`
+ * callback into a positioned `<div>`.
+ *
+ * Returns a cleanup function that removes the listeners and the tooltip
+ * element. Idempotent — calling cleanup twice is a no-op.
+ *
+ * Style the tooltip via CSS:
+ *
+ * ```css
+ * .mlc-tooltip {
+ *   position: absolute;
+ *   pointer-events: none;
+ *   padding: 6px 10px;
+ *   background: rgba(15, 23, 42, 0.92);
+ *   color: #fff;
+ *   border-radius: 4px;
+ *   font-size: 12px;
+ *   transform: translate(8px, 8px);
+ * }
+ * .mlc-tooltip__time { opacity: 0.7; margin-bottom: 4px; }
+ * .mlc-tooltip__name { opacity: 0.8; }
+ * ```
+ */
+declare function attachTooltip(target: HTMLElement, chart: MLTimeGraph, options?: TooltipOptions): () => void;
+
+/*!
+ * 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.
+ */
+
+/** Options accepted by {@link mount} on top of `MLTimeGraphOptions`. */
+interface MountOptions extends MLTimeGraphOptions {
+    /**
+     * Attach a DOM tooltip. The library finds the nearest sample per
+     * series at the cursor's X position, renders the result via the
+     * `format` callback into an absolutely-positioned `<div>`.
+     *
+     * Pass `{ show: true }` to use the default formatter (time header +
+     * `name: value` per series), or supply your own `format(samples)`
+     * for full control over the markup.
+     */
+    tooltip?: TooltipOptions;
+}
+/**
+ * Create a chart and inject its SVG into `target` in one call.
+ *
+ * Replaces the manual three-step boilerplate:
+ *   const chart = new MLTimeGraph({...});
+ *   const { content } = new SVGRenderer().render(chart.renderCommands());
+ *   el.innerHTML = content;
+ *
+ * Width defaults to the target's measured width (falls back to 800),
+ * height to the explicit option or 350. The `<svg>` is left responsive
+ * (`width="100%"`, viewBox set to the rendered dimensions) so the chart
+ * scales with its container.
+ *
+ * Optionally attaches an interactive tooltip via `options.tooltip` —
+ * see {@link attachTooltip} for the full options surface.
+ *
+ * Returns the chart instance — useful for later `invertTime` /
+ * `invertValue` / `setData` calls.
+ *
+ * @param target  DOM element to render into, or a CSS selector string
+ *                resolved against `document` (throws if not found).
+ */
+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.
+ */
+
+declare class SVGRenderer extends Renderer {
+    #private;
+    constructor(options?: {
+        width?: number | string;
+        height?: number | string;
+    });
+    render(commands: DrawCommand[]): RenderOutput;
+    _toSVG(cmd: DrawCommand): string;
+    /** Register or retrieve a hatch pattern by variant. Returns the pattern id for use as fill="url(#id)". */
+    _hatchPattern(variant: string, fillColor: string | undefined): string;
+    /** Monotonic counter for unique hatch pattern ids. */
+    _hatchIndex: number;
+    _path(c: Extract<DrawCommand, {
+        type: "path";
+    }>): string;
+    _line(c: Extract<DrawCommand, {
+        type: "line";
+    }>): string;
+    _rect(c: Extract<DrawCommand, {
+        type: "rect";
+    }>): string;
+    _circle(c: Extract<DrawCommand, {
+        type: "circle";
+    }>): string;
+    _gradient(c: Extract<DrawCommand, {
+        type: "gradient";
+    }>): string;
+    _gap(c: Extract<DrawCommand, {
+        type: "gap";
+    }>): string;
+    _group(c: Extract<DrawCommand, {
+        type: "group";
+    }>): string;
+    _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.
+ */
+
+/** Input shape for {@link fillBetweenThresholds}. */
+interface FillBetweenThresholdsInput {
+    /** Threshold names in ascending value order (low → high). */
+    thresholds: string[];
+    /** One colour per zone — must be exactly `thresholds.length + 1` entries. */
+    colors: string[];
+    /** Optional hatch pattern per zone (`undefined` slots are plain colour). */
+    hatches?: (HatchVariant | undefined)[];
+}
+/**
+ * Build a {@link FillSpec} that paints the area beneath the series in
+ * stacked zones, partitioned by N named thresholds. Returns N+1 regions:
+ *
+ *   region 0          chartBottom .. threshold[0]
+ *   region 1..N-1     threshold[i-1] .. threshold[i]
+ *   region N          threshold[N-1] .. series   (i.e. up to the line)
+ *
+ * Mirrors the legacy `fillByThresholds` + `fillByThresholdsHatches`
+ * combination but as a single, composable, type-safe call.
+ *
+ * @example
+ * style: {
+ *   fill: fillBetweenThresholds({
+ *     thresholds: ['cold', 'norm', 'hot'],
+ *     colors:     ['#60a5fa33', '#22c55e33', '#fbbf2433', '#ef444433'],
+ *     hatches:    ['classic-diagonal', 'crosshatch', 'dots', 'waves'],
+ *   }),
+ * }
+ */
+declare function fillBetweenThresholds(input: FillBetweenThresholdsInput): FillSpec;
+
+/*!
+ * 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.
+ */
+
+/**
+ * Parse raw JSON to internal DataPoint format.
+ * Validiert: time (ms-Timestamp, number), value (number).
+ */
+declare function parseDataPoint(obj: unknown): DataPoint;
+/** Parse raw JSON array to TimeSeries[] or raw DataPoint[] */
+declare function parseSeries(obj: unknown): TimeSeries | DataPoint[];
+/** Parse aggregated series (AggregatedPoint[] — min/max/avg per slot) */
+declare function parseAggregated(obj: unknown): AggregatedSeries;
+
+/*!
+ * 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.
+ */
+
+/** The Theme type — same shape as the immutable BUILTIN_DEFAULTS object. */
+type Theme = typeof theme;
+/**
+ * Apply a partial override on top of the current global default theme.
+ * Merged shallowly — nested objects (e.g. {@link Theme.palette}) are replaced
+ * wholesale, not deep-merged.
+ *
+ * @example
+ * setDefaultTheme({ stroke: '#0f172a', gridStroke: '#f1f5f9' });
+ * new MLTimeGraph({ ... }); // picks up the new defaults
+ */
+declare function setDefaultTheme(partial: Partial<Theme>): void;
+/**
+ * Read the current global default theme (a snapshot — mutating the result
+ * does NOT affect future reads).
+ */
+declare function getDefaultTheme(): Readonly<Theme>;
+/**
+ * Restore the global default theme to the library's built-in values
+ * (`BUILTIN_DEFAULTS` from {@link ./defaults.ts}). Useful in test
+ * `afterEach` hooks and when you want to undo a previous `setDefaultTheme`.
+ */
+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 };