ml-time-graph 1.0.0

package/dist/scale-Cbr0KpPz.d.ts

@@ -0,0 +1,824 @@
+/*!
+ * 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.
+ */
+/** Shared SVG/CSS shadow and glow effects for draw commands. */
+interface DrawEffects {
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: 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.
+ */
+/** Gradient-Stop */
+interface GradientStop {
+    offset: number;
+    color: 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.
+ */
+/** Koordinaten-Punkt (Pixel) */
+interface Point {
+    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.
+ */
+/** All available line-stroke variants. */
+type LineVariant = "solid" | "dotted" | "sparse-dots" | "dashed" | "long-dash" | "dense-dash" | "dash-dot" | "dash-dot-dot" | "loose-dash";
+
+/**
+ * Stroke pattern for path / line draw commands. Widened to {@link LineVariant}
+ * in Phase 2 (was: `'dashed' | 'dotted'`). The legacy values still work; the
+ * renderer keeps their exact visual output (4,4 / 2,4 dashes) for backwards
+ * compatibility, and uses `getLineStyle()` to scale newer variants
+ * proportionally to the stroke width.
+ */
+type Dashstyle_t = LineVariant;
+interface DrawPath extends DrawEffects {
+    type: 'path';
+    points: Point[];
+    smoothing?: boolean;
+    stroke?: string;
+    strokeWidth?: number;
+    fill?: string;
+    hatch?: string;
+    dashed?: boolean;
+    /** Dash style; overrides `dashed`. */
+    dash?: Dashstyle_t;
+    opacity?: number;
+    /** Optional SVG `id` attribute for this element. */
+    id?: string;
+}
+interface DrawLine extends DrawEffects {
+    type: 'line';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stroke?: string;
+    strokeWidth?: number;
+    dashed?: boolean;
+    /** Dash style; overrides `dashed`. */
+    dash?: Dashstyle_t;
+    opacity?: number;
+    /** Optional SVG `id` attribute for this element. */
+    id?: string;
+}
+interface DrawRect extends DrawEffects {
+    type: 'rect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    fill?: string;
+    hatch?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    dashed?: boolean;
+    /** Optional SVG `id` attribute for this element. */
+    id?: string;
+}
+interface DrawCircle extends DrawEffects {
+    type: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+    fill?: string;
+    hatch?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Optional SVG `id` attribute for this element. */
+    id?: string;
+}
+interface DrawText {
+    type: 'text';
+    content: string;
+    x: number;
+    y: number;
+    anchor?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fill?: string;
+    /** Rotation in degrees, around (x, y). Used e.g. for vertical axis labels. */
+    rotate?: number;
+    textBaseline?: 'top' | 'middle' | 'bottom';
+    /** Optional SVG `id` attribute for this element. */
+    id?: string;
+}
+type DrawDirection_t = 'vertical' | 'horizontal';
+interface DrawGradient {
+    type: 'gradient';
+    points: Point[];
+    stops: GradientStop[];
+    direction: DrawDirection_t;
+}
+type DrawGapType_t$1 = 'dashed_border' | 'empty' | 'label';
+interface DrawGap {
+    type: 'gap';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    style: DrawGapType_t$1;
+    label?: string;
+    /** Optional SVG `id` attribute for this element. */
+    id?: string;
+}
+interface DrawGroup {
+    type: 'group';
+    commands: DrawCommand[];
+    cssClass?: string;
+    /** Optional SVG `id` attribute for this group. */
+    id?: string;
+    plotClipId?: string;
+    /** Plot-area rectangle. When set the SVGRenderer emits a matching `<clipPath>` in \<defs\> and applies `clip-path` to this group. */
+    clipRect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/** Union aller Commands */
+type DrawCommand = DrawPath | DrawLine | DrawRect | DrawCircle | DrawText | DrawGradient | DrawGap | DrawGroup;
+type LineParams = Omit<DrawLine, 'type'>;
+type PathParams = Omit<DrawPath, 'type'>;
+type RectParams = Omit<DrawRect, 'type'>;
+type CircleParams = Omit<DrawCircle, 'type'>;
+type TextParams = Omit<DrawText, 'type'>;
+
+/*!
+ * 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.
+ */
+/** Point marker style — unified for series points, annotations, and markers. */
+type PointStyleType = "none" | "circle" | "cross" | "square" | "diamond" | "triangle" | "star" | "arrow" | "plus" | "triangle-down" | "hexagon" | "hourglass" | "line-horizontal";
+/** Chart series type (determines which renderer pipeline is used). */
+type SeriesType = "line" | "area" | "step";
+/** Line dashes style. 'none' means the line is not drawn at all. */
+type LineDashStyle = "solid" | "dashed" | "dotted" | "none";
+/** Direction for zoned fills relative to the line. */
+type FillDirectionType = "toMin" | "toMax";
+/** Side of a threshold or value for fill rendering. */
+type FillSide = "above" | "below";
+/** Axis orientation: vertical (left/right Y-axis) or horizontal (bottom X-axis). */
+type AxisOrientation = "vertical" | "horizontal";
+/** Vertical axis placement. */
+type AxisPosition = "left" | "right";
+/** Text anchor alignment. */
+type LabelAnchor = "start" | "middle" | "end";
+/** Gap rendering style. */
+type DrawGapType_t = "dashed_border" | "empty" | "label";
+
+/*!
+ * 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.
+ */
+/** All available hatch and pattern variants. */
+type HatchVariant = "none" | "classic-diagonal" | "dense-steep" | "crosshatch" | "dots" | "waves" | "dashed" | "herringbone" | "brick" | "double-stripe" | "honeycomb";
+/**
+ * Produce an SVG `<pattern>` element for the given variant.
+ * @param id        DOM id to reference the pattern from `fill="url(#id)"`.
+ * @param variant   Visual pattern kind (default `classic-diagonal`).
+ * @param fillcolor Pattern background colour (default a light steel-blue).
+ * @param linecolor Foreground stroke colour for the pattern shapes.
+ * @param strokewidth Stroke width in user units (scales with the pattern).
+ */
+declare function getHatch(id: string, variant?: HatchVariant, fillcolor?: string, linecolor?: string, strokewidth?: number): 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.
+ */
+
+/**
+ * A fill description. Three shapes:
+ *  - `string` — plain colour (`'#ef444433'` or `'rgba(…)'`)
+ *  - `{ color }` — explicit colour
+ *  - `{ color, hatch, hatchColor?, hatchWidth? }` — colour + hatch pattern
+ *
+ * Where the fill is applied is described by {@link FillRegion}, not by `FillStyle`.
+ */
+type FillStyle = string | {
+    color: string;
+    hatch?: HatchVariant;
+    hatchColor?: string;
+    hatchWidth?: number;
+};
+/** Vertical boundary of a fill region. */
+type FillBound = "series" | "chartTop" | "chartBottom" | {
+    threshold: string;
+} | {
+    value: number;
+};
+/**
+ * A fill region. `from` and `to` define the Y interval; the X range is always
+ * the series itself.
+ */
+interface FillRegion {
+    /** Lower bound. Default `'chartBottom'`. */
+    from?: FillBound;
+    /** Upper bound. Default `'series'` (the line). */
+    to?: FillBound;
+    /** The fill itself. */
+    fill: FillStyle;
+    /** Only fill on one side of the `from`/`to` transition. */
+    side?: "above" | "below";
+    /**
+     * Optional outer gate. With `side` set and exactly one bound being
+     * `'series'`, the region renders only in X-spans where the line's value
+     * is between the fixed inner bound and this outer bound:
+     *  - `side: 'above'` → outer > inner; render where inner < value < outer.
+     *  - `side: 'below'` → outer < inner; render where outer < value < inner.
+     *
+     * Use this for classified zone bands: stack four bands lowwarn / low /
+     * high / highwarn and each fills only its own value range.
+     */
+    outer?: FillBound;
+}
+/**
+ * Top-level fill spec on a series style. Either a single fill (covers from
+ * chart bottom to the line) or a `regions[]` array for multi-zone fills.
+ */
+type FillSpec = FillStyle | {
+    regions: FillRegion[];
+};
+
+/*!
+ * 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.
+ */
+
+/** Label placement / styling inside a gap region. */
+interface GapLabel {
+    baseline?: "above" | "middle" | "below";
+    rotate?: number;
+    color?: string;
+    fontSize?: number;
+}
+/** Visual styling of a gap region. */
+interface GapStyle {
+    /**
+     * - `'empty'`         — line breaks, gap is not visualised.
+     * - `'dashed_border'` — dashed-stroke rectangle over the gap span (default
+     *                       when no `fill` is given).
+     * - `'filled'`        — filled rectangle (use with `fill`).
+     * - `'bridge_line'`   — dotted/dashed line between the last point before
+     *                       the gap and the first one after — "missing data"
+     *                       made visible without a background fill.
+     */
+    display?: "empty" | "dashed_border" | "filled" | "bridge_line";
+    fill?: FillStyle;
+    opacity?: number;
+    label?: GapLabel;
+    /** Optional bridge-line style; only used when `display: 'bridge_line'`. */
+    bridge?: {
+        color?: string;
+        width?: number;
+        /** Default `'dotted'`. */
+        style?: "solid" | "dotted" | "dashed";
+    };
+}
+/** A manually-declared gap region. */
+interface GapRegion {
+    startTime: number;
+    endTime: number;
+    label?: string;
+    style?: GapStyle;
+}
+/** Top-level gap configuration on `MLTimeGraphOptions`. */
+interface GapsConfig {
+    autoDetect?: boolean;
+    minGapMs?: number;
+    regions?: GapRegion[];
+    style?: GapStyle;
+}
+
+/*!
+ * 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.
+ */
+
+/** Line styling for a series. All fields optional; defaults come from the theme. */
+interface LineStyle {
+    /** Stroke colour. */
+    color?: string;
+    /** Stroke width in px. */
+    width?: number;
+    /** Stroke variant (`solid` / `dashed` / `dotted` / …). */
+    style?: LineVariant;
+    /** Catmull-Rom smoothing. */
+    smoothing?: boolean;
+    /** Line shape — `line` (Default) or `step` (Treppe). */
+    shape?: "line" | "step";
+    /** Max time gap (ms) between samples before the line breaks; 0 = off. */
+    gapThreshold?: number;
+    /** Opacity 0..1 (e.g. for overlaid lines). */
+    opacity?: number;
+}
+/** Drop-shadow for line / markers. */
+interface ShadowStyle {
+    color?: string;
+    blur?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+/** Marker / point styling on series samples. */
+interface MarkerStyle {
+    /** Marker shape (default `none`). */
+    type?: PointStyleType;
+    /** Marker size in px (radius or half-width). */
+    size?: number;
+    /** Outline colour. */
+    stroke?: string;
+    /** Fill colour. */
+    fill?: string;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Show markers only if the series has ≤ n samples (anti-clutter). */
+    threshold?: number;
+}
+/**
+ * Visual styling for a series. Which sub-objects are present determines what
+ * gets drawn: `line` → line, `fill` → area, `markers` → points. Any
+ * combination is allowed. Defaults come from the theme.
+ */
+interface SeriesStyle {
+    /** Optional id prefix for DOM selectors. */
+    id?: string;
+    /**
+     * Line styling. Three forms: a single `LineStyle`, an array (multiple lines
+     * through the same data — e.g. step + smoothed overlay), or `false` to skip
+     * the line entirely.
+     */
+    line?: LineStyle | LineStyle[] | false;
+    /** Area / fill spec. */
+    fill?: FillSpec;
+    /** Point-marker styling. */
+    markers?: MarkerStyle;
+    /** Drop-shadow for line + markers. */
+    shadow?: ShadowStyle;
+    /** Per-series override for the gap rendering. */
+    gap?: GapStyle;
+}
+
+/*!
+ * 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.
+ */
+
+/**
+ * Statistic overlay on a series. Discriminated by `kind`.
+ *
+ * - `movingAverage` — simple or exponential moving average over a `window` ms.
+ * - `movingMkt`     — rolling Mean Kinetic Temperature (USP <1079.2>) over a
+ *                     `window` ms; `activationEnergy` defaults to 83144 J/mol.
+ * - `stdDevBand`    — band of (rolling-mean ± `multiplier` × σ) over `window` ms;
+ *                     `multiplier` defaults to 1. `style.fill` controls the band
+ *                     fill (FillStyle); `style.line`, if set, also renders the
+ *                     centerline.
+ * - `limits`        — horizontal `low` / `high` reference lines + flagging
+ *                     of out-of-bounds excursions.
+ */
+type SeriesOverlay = {
+    kind: "movingAverage";
+    window: number;
+    type?: "simple" | "exponential";
+    style?: SeriesStyle;
+} | {
+    kind: "movingMkt";
+    window: number;
+    activationEnergy?: number;
+    style?: SeriesStyle;
+} | {
+    kind: "stdDevBand";
+    window: number;
+    multiplier?: number;
+    style?: SeriesStyle;
+} | {
+    kind: "limits";
+    low?: number;
+    high?: number;
+    style?: SeriesStyle;
+};
+/** All overlay kinds — useful for switch-statement exhaustiveness checks. */
+type SeriesOverlayKind = SeriesOverlay["kind"];
+
+/*!
+ * 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.
+ */
+
+/** Einzelner Messwert — numerisch oder Integer-Enum-Key */
+interface DataPoint {
+    /** Zeit (ms-Timestamp) */
+    time: number;
+    /** Numerischer Wert oder Integer-Enum-Key, null = Gap (Linie bricht hier) */
+    value: number | null;
+    /** Optionaler Annotationstext */
+    annotation?: string;
+    /**
+     * Synthetischer Punkt — keine echte Messung. Wird automatisch vom
+     * `SeriesProcessor` auf interpolierten Punkten gesetzt (Threshold-Schnitte,
+     * Gap-Ränder), kann auch manuell verwendet werden für eigene berechnete
+     * Stützstellen (z. B. eine Trendlinie auf interpolierten Zwischenwerten).
+     *
+     * Renderer-Konsequenz: kein Punkt-Marker, kein Tooltip-Snap, kein Eintrag
+     * in der Werte-Tabelle. Skalen (Y-Min/Max) zählen den Punkt mit, sonst
+     * wäre die Linien-Geometrie verzerrt. Default `undefined` = echte Messung.
+     *
+     * Siehe API_DESIGN.md §4.1.
+     */
+    synthetic?: boolean;
+}
+/**
+ * Limits + activation energy for pre-computed slot-level statistics (MKT,
+ * minutes-above/below). When passed to `aggregateBySlot`, the returned
+ * slots are widened to `StatsAggregatedPoint`. At render time, an
+ * equivalent on-the-fly variant is the `limits` / `movingMkt` overlay.
+ */
+interface AggregationThresholds {
+    limitLow: number;
+    limitHigh: number;
+    activationEnergy?: number;
+}
+/** Aggregierter Messwert pro Zeitslot (hourly/daily/custom). */
+interface AggregatedPoint {
+    /** Slot-Start-Zeit (ms) */
+    time: number;
+    /** Minimum-Wert, null = Gap-Slot */
+    min: number | null;
+    /** Maximum-Wert, null = Gap-Slot */
+    max: number | null;
+    /** Durchschnitt, null = Gap-Slot */
+    avg: number | null;
+    /** Anzahl der Roh-Daten im Slot */
+    count: number;
+}
+/** Sensor-Typ */
+type SensorType = "numeric" | "enum";
+/** Map from enum value (number) to human-readable label */
+interface EnumMap {
+    [key: number]: string;
+}
+/** Raw-Serie (numerisch oder Enum) */
+interface TimeSeries {
+    name: string;
+    data: DataPoint[];
+    sensorType?: SensorType;
+    enumMap?: EnumMap;
+    /**
+     * Structured style block (preferred, see API_DESIGN.md §5).
+     * The structured style block. Its sub-objects (`line`, `fill`, `markers`,
+     * `shadow`, `gap`) are merged with theme defaults by the chart's resolver.
+     */
+    style?: SeriesStyle;
+    /**
+     * Statistic overlays computed at render time from this series' data.
+     * Each overlay carries its own style and appears in the legend.
+     * See API_DESIGN.md §11.
+     */
+    overlays?: SeriesOverlay[];
+    yAxisIndex?: number;
+    seriesType?: SeriesType;
+    /** Color the line by these named thresholds — segments are coloured per zone. */
+    colorByThresholds?: string[];
+    /** Optional SVG id prefix for series elements. */
+    id?: string;
+}
+/** Aggregierte Serie: min/max/avg pro Slot */
+interface AggregatedSeries {
+    name: string;
+    data: AggregatedPoint[];
+    /** 'band' = gefülltes Rechteck pro Slot; 'minmaxavg' = min/max/avg-Linien + optionaler Fill */
+    showAs?: "band" | "minmaxavg";
+    yAxisIndex?: number;
+    avgLine?: boolean;
+    countOpacity?: boolean;
+    /**
+     * Structured style block (preferred). For aggregated series, `style.line.color`
+     * sets the avg-line colour; `style.fill.color` sets the band fill.
+     * Sub-band fills (avg→max, avg→min) keep using the legacy `fillToMax`/`fillToMin`
+     * for now — the new `style.fill.regions[]` form covers them and arrives in 2.9.
+     */
+    style?: SeriesStyle;
+    /** Statistic overlays — see API_DESIGN.md §11. */
+    overlays?: SeriesOverlay[];
+    minColor?: string;
+    maxColor?: string;
+    avgColor?: string;
+    /** avg gepunktet (default: true). */
+    avgDashed?: boolean;
+    /** Halbtransparenter Fill zwischen avg and max */
+    fillToMax?: string;
+    /** Hatch pattern for fillToMax */
+    fillToMaxHatch?: HatchVariant;
+    /** Halbtransparenter Fill zwischen avg and min */
+    fillToMin?: string;
+    /** Hatch pattern for fillToMin */
+    fillToMinHatch?: HatchVariant;
+    /** Optional SVG id prefix for series elements. */
+    id?: string;
+}
+/** Series-Typ: Raw, Enum, oder Aggregat */
+type AnySeries = TimeSeries | AggregatedSeries;
+/** Time range gap with optional label and style */
+interface Gap {
+    startTime: number;
+    endTime: number;
+    label?: string;
+    fill?: string;
+    /** Hatch pattern for gap fill */
+    hatch?: HatchVariant;
+    fillOpacity?: number;
+    labelBaseline?: 'above' | 'middle' | 'below';
+    rotate?: number;
+    style?: DrawGapType_t$1;
+}
+/** Configuration for gap rendering (manual or auto-detected) */
+interface GapConfig {
+    enabled: boolean;
+    autoDetect?: boolean;
+    minGapMs?: number;
+    gaps?: Gap[];
+}
+/** Possible positions for threshold labels */
+type ThresholdLabelPosition = "left" | "right" | "above" | "below" | "center";
+interface ThresholdLabelConfig {
+    /** Label text (default: the threshold's name). */
+    text?: string;
+    /** Where the label sits relative to the line (default: 'right'). */
+    position?: ThresholdLabelPosition;
+    /** Rotation in degrees (default: none). */
+    rotate?: number;
+    /** Text vertical alignment: 'top', 'middle' (default), or 'bottom'. */
+    textBaseline?: "top" | "middle" | "bottom";
+}
+/**
+ * A named value boundary. It can be drawn (line / half-plane fill / label) and
+ * referenced from a series via `colorByThresholds` / `fillToThreshold`.
+ */
+interface Threshold {
+    name: string;
+    value: number;
+    color?: string;
+    line?: "solid" | "dashed" | "dotted" | "none";
+    fill?: "above" | "below" | "none";
+    fillHatch?: HatchVariant;
+    fillOpacity?: number;
+    label?: false | string | ThresholdLabelConfig;
+    /** Optional SVG id prefix for threshold elements. Generated ids: `<id>-line`, `<id>-fill`, `<id>-label`. */
+    id?: string;
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: number;
+}
+/** Colored time-range highlight drawn behind the series */
+interface Highlight {
+    startTime: number;
+    endTime: number;
+    label?: string;
+    color?: string;
+    opacity?: number;
+    /**
+     * Where the label sits (default 'top'). 'top' | 'center' | 'bottom' are inside
+     * the highlighted band; 'above' / 'below' place it outside the plot area
+     * (in the top margin / below the x-axis) so it never overlaps the data.
+     */
+    labelPosition?: "top" | "center" | "bottom" | "above" | "below";
+}
+/** A point in data coordinates. `axis` selects the y-scale (0 = left, 1 = right). */
+interface DataPointRef {
+    time: number;
+    value: number;
+    axis?: number;
+}
+/**
+ * A free-form, user-supplied overlay drawn in data coordinates (time/value).
+ * The chart projects it to pixels, so it tracks the data through zoom/resize.
+ * An optional `id` lets you remove or enable/disable it dynamically.
+ */
+type Annotation = {
+    id?: string;
+} & ({
+    type: "line";
+    from: DataPointRef;
+    to: DataPointRef;
+    color?: string;
+    width?: number;
+    dash?: "dashed" | "dotted";
+} | {
+    type: "arrow";
+    from: DataPointRef;
+    to: DataPointRef;
+    color?: string;
+    width?: number;
+    headSize?: number;
+} | {
+    type: "rect";
+    from: DataPointRef;
+    to: DataPointRef;
+    fill?: string;
+    hatch?: HatchVariant;
+    stroke?: string;
+    opacity?: number;
+} | {
+    type: "point";
+    at: DataPointRef;
+    color?: string;
+    radius?: number;
+    shape?: "circle" | "square" | "cross";
+} | {
+    type: "label";
+    at: DataPointRef;
+    text: string;
+    color?: string;
+    anchor?: "start" | "middle" | "end";
+    dx?: number;
+    dy?: number;
+    rotate?: number;
+});
+/** Aggregation mode: no aggregation, hourly, daily, or custom interval */
+type AggregationMode = "none" | "hourly" | "daily" | "custom";
+interface AggregationConfig {
+    mode: AggregationMode;
+    interval?: number;
+}
+/**
+ * A colored time-range item inside an annotation band.
+ * Drawn as a rect strip spanning the band height, with optional label.
+ */
+interface AnnotationBandItem {
+    /** Start time (ms epoch) */
+    startTime: number;
+    /** End time (ms epoch) */
+    endTime: number;
+    /** Fill color for this range (default '#6b728044'). */
+    fill?: string;
+    /** Hatch pattern for band item fill */
+    hatch?: HatchVariant;
+    /** Stroke color for the rect border (default: none). */
+    stroke?: string;
+    /** Stroke width (default: 0). */
+    strokeWidth?: number;
+    /** Optional label centered in this range. */
+    label?: string;
+    /** Label font size in px (default: 10). */
+    labelFontSize?: number;
+    /** Label fill color (default: inherit from theme). */
+    labelFill?: string;
+    /**
+      * Label vertical position: 'top', 'middle' (default), or 'bottom' inside the band.
+      */
+    labelBaseline?: 'top' | 'middle' | 'bottom';
+}
+/**
+ * Configuration for an annotation band — a horizontal strip below the main chart
+ * that shares the time axis and highlights time ranges with colors and optional labels.
+ */
+interface AnnotationBandConfig {
+    /** Name of this band (used for legend / grouping). */
+    name: string;
+    /** Default hatch pattern for all items in this band (overridden per-item). */
+    hatch?: HatchVariant;
+    /** Band height in pixels (default: 12). */
+    height?: number;
+    /** Pixel offset between bands (default: 0). */
+    spacing?: number;
+    /** Whether to show a time axis for this band (default: false). */
+    showAxis?: boolean;
+    /** Whether this band should appear in the legend (default: true). */
+    showInLegend?: boolean;
+    /** Background fill for the entire band (default: transparent). */
+    background?: string;
+    /** Colored time ranges to draw in this band. */
+    items: AnnotationBandItem[];
+}
+
+/*!
+ * 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.
+ */
+/** Base scale interface – maps data values to pixel coordinates */
+interface ScaleConfig {
+    /** Pixel range (output domain). Defaults to [0, width] or [0, height] */
+    range: [number, number];
+}
+interface Scale {
+    /** Map a data value to a pixel coordinate */
+    map(value: unknown): number;
+    /** Map a pixel coordinate back to a data value */
+    invert(pixel: number): unknown;
+    /** Get the data domain */
+    domain(): [unknown, unknown];
+    /** Get the pixel range */
+    range(): [number, number];
+}
+/** Scale with explicit data domain and pixel range. */
+interface DomainScaleConfig extends ScaleConfig {
+    domain: [unknown, unknown];
+}
+/** Configuration for linear value-to-pixel mapping. */
+interface LinearScaleConfig {
+    domain: [number, number];
+    range: [number, number];
+}
+/** Maps numeric data values to pixel coordinates using linear interpolation. */
+declare class LinearScale implements Scale {
+    #private;
+    constructor(config: LinearScaleConfig);
+    map(value: unknown): number;
+    invert(pixel: number): number;
+    domain(): [number, number];
+    range(): [number, number];
+}
+/** Nice time intervals for tick placement (milliseconds) */
+declare const TIME_INTERVALS: {
+    label: string;
+    ms: number;
+}[];
+/** Configuration for time-to-pixel mapping. */
+interface TimeScaleConfig {
+    domain: [number, number];
+    range: [number, number];
+    /** Locale for i18n formatting (default: 'en-US') */
+    locale?: string;
+}
+/** Maps timestamps (ms) to pixel coordinates with automatic tick interval selection. */
+declare class TimeScale implements Scale {
+    #private;
+    constructor(config: TimeScaleConfig);
+    map(value: unknown): number;
+    invert(pixel: number): number;
+    domain(): [number, number];
+    range(): [number, number];
+    get locale(): string;
+    /**
+     * Pick the "nicest" time interval that yields roughly `targetTicks` ticks
+     * across the visible range. Clamps to minTicks / maxTicks bounds.
+     */
+    tickInterval(targetTicks: number, minTicks?: number, maxTicks?: number): {
+        interval: number;
+    };
+    /**
+     * Generate tick positions (timestamps) across the domain.
+     */
+    ticks(opts?: {
+        minTicks?: number;
+        maxTicks?: number;
+    }): number[];
+    /** Format a timestamp using Intl.DateTimeFormat */
+    format(timestamp: number, formatOpts?: Intl.DateTimeFormatOptions): string;
+}
+/** Configuration for band (categorical) scale. */
+interface BandScaleConfig {
+    /** Discrete categories (strings or numbers) */
+    domain: string[];
+    range: [number, number];
+    /** Padding fraction inside the band area (0-1, default 0.1) */
+    paddingInner?: number;
+    /** Padding fraction outside the band area (0-1, default 0.05) */
+    paddingOuter?: number;
+}
+/** Scale for discrete (categorical) axes — maps category indices to pixel positions. */
+declare class BandScale implements Scale {
+    #private;
+    constructor(config: BandScaleConfig);
+    /** Get the pixel width of each band (including padding) */
+    get step(): number;
+    /** Get the pixel width of each band's content area */
+    get bandwidth(): number;
+    map(value: unknown): number;
+    invert(pixel: number): string;
+    domain(): [string, string];
+    range(): [number, number];
+    /** Get all band positions */
+    positions(): Map<string, number>;
+}
+
+export { type PointStyleType as $, type AggregatedPoint as A, BandScale as B, type CircleParams as C, type Dashstyle_t as D, type EnumMap as E, type FillBound as F, type FillSide as G, type FillSpec as H, type FillStyle as I, type Gap as J, type GapConfig as K, type GapLabel as L, type GapRegion as M, type GapStyle as N, type GapsConfig as O, type HatchVariant as P, type Highlight as Q, type LabelAnchor as R, type LineDashStyle as S, type LineParams as T, type LineStyle as U, type LineVariant as V, LinearScale as W, type LinearScaleConfig as X, type MarkerStyle as Y, type PathParams as Z, type Point as _, type AggregatedSeries as a, type RectParams as a0, type Scale as a1, type ScaleConfig as a2, type SensorType as a3, type SeriesOverlay as a4, type SeriesOverlayKind as a5, type SeriesStyle as a6, type SeriesType as a7, type ShadowStyle as a8, TIME_INTERVALS as a9, type TextParams as aa, type Threshold as ab, type ThresholdLabelConfig as ac, type ThresholdLabelPosition as ad, TimeScale as ae, type TimeScaleConfig as af, type TimeSeries as ag, getHatch as ah, type AggregationConfig as b, type AggregationMode as c, type AggregationThresholds as d, type Annotation as e, type AnnotationBandConfig as f, type AnnotationBandItem as g, type AnySeries as h, type AxisOrientation as i, type AxisPosition as j, type BandScaleConfig as k, type DataPoint as l, type DataPointRef as m, type DomainScaleConfig as n, type DrawCircle as o, type DrawCommand as p, type DrawGap as q, type DrawGapType_t as r, type DrawGradient as s, type DrawGroup as t, type DrawLine as u, type DrawPath as v, type DrawRect as w, type DrawText as x, type FillDirectionType as y, type FillRegion as z };