ml-time-graph 1.0.0

package/dist/internals.d.ts

@@ -0,0 +1,899 @@
+import { M as Marker } from './layout-Sc5UkC0r.js';
+export { L as Layout, a as LayoutConfig, b as LayoutResult, c as LegendConfig, d as LegendItem, e as LegendOrientation, f as Renderer, m as measureLegend, r as renderLegend, t as theme } from './layout-Sc5UkC0r.js';
+import { A as AggregatedPoint, ae as TimeScale, W as LinearScale, $ as PointStyleType, p as DrawCommand, l as DataPoint, ab as Threshold, J as Gap, P as HatchVariant, Q as Highlight, e as Annotation, E as EnumMap, B as BandScale, _ as Point, g as AnnotationBandItem, V as LineVariant, H as FillSpec, N as GapStyle, ag as TimeSeries } from './scale-Cbr0KpPz.js';
+export { i as AxisOrientation, j as AxisPosition, k as BandScaleConfig, C as CircleParams, D as Dashstyle_t, n as DomainScaleConfig, o as DrawCircle, q as DrawGap, r as DrawGapType_t, s as DrawGradient, t as DrawGroup, u as DrawLine, v as DrawPath, w as DrawRect, x as DrawText, R as LabelAnchor, T as LineParams, X as LinearScaleConfig, Z as PathParams, a0 as RectParams, a1 as Scale, a2 as ScaleConfig, a9 as TIME_INTERVALS, aa as TextParams, af as TimeScaleConfig, ah as getHatch } 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.
+ */
+
+/**
+ * Flat style configuration for series rendering.
+ * All fields are optional — defaults are applied internally via `resolveStyle()`.
+ */
+interface SeriesStyle {
+    /** Stroke color. */
+    stroke?: string;
+    /** Stroke width in pixels. */
+    strokeWidth?: number;
+    /** Enable Catmull-Rom smoothing. */
+    smoothing?: boolean;
+    /** Enable dashed line style. */
+    dashed?: boolean;
+    /** Fill colour (hex, rgba, or `url(#gradient-id)`). */
+    fill?: string;
+    /** Hatch pattern for fill (default: none). */
+    hatch?: string;
+    /** Data-point marker style. */
+    pointStyle?: PointStyleType;
+    /** Marker size (radius or half-width). */
+    pointSize?: number;
+    /** Marker outline colour. Default: same as the line's stroke (per-point). */
+    pointStroke?: string;
+    /** Marker fill colour. Default: same as the line's stroke. */
+    pointFill?: string;
+    /** Marker outline width. Default: 1.5. */
+    pointStrokeWidth?: number;
+    /** Shadow color. */
+    shadowColor?: string;
+    /** Shadow blur in pixels. */
+    shadowBlur?: number;
+    /** Shadow X offset. */
+    shadowOffsetX?: number;
+    /** Shadow Y offset. */
+    shadowOffsetY?: number;
+    /** SVG id prefix for all elements generated by this style. */
+    id?: string;
+}
+interface RenderingContext {
+    timeScale: TimeScale;
+    valueScale: LinearScale;
+}
+/** Render segments as continuous lines (standard or smoothed). */
+declare function renderLine(segments: {
+    data: DataPoint[];
+    color?: string;
+}[], ctx: RenderingContext, style: SeriesStyle): DrawCommand[];
+/** Render segments as step-functions. */
+declare function renderStep(segments: {
+    data: DataPoint[];
+    color?: string;
+}[], ctx: RenderingContext, style: SeriesStyle): DrawCommand[];
+/** Render segments as a filled area between two values (e.g. min/max band). */
+declare function renderArea(segments: {
+    data: AggregatedPoint[];
+    color?: string;
+}[], ctx: RenderingContext, style: SeriesStyle, yLow: (p: AggregatedPoint) => number, yHigh: (p: AggregatedPoint) => number): DrawCommand[];
+/**
+ * Complex area renderer that splits a run by value boundaries (thresholds)
+ * and renders the resulting zones as separate filled areas.
+ */
+declare function renderZonedArea<T>(run: T[], ctx: RenderingContext, options: {
+    boundaries: number[];
+    yLow: (p: T) => number;
+    yHigh: (p: T) => number;
+    getValue: (p: T) => number;
+    interpolate: (p1: T, p2: T, t: number) => T;
+    getColor: (zoneIndex: number) => string | undefined;
+    getHatch?: (zoneIndex: number) => string | undefined;
+}, style?: SeriesStyle): DrawCommand[];
+/**
+ * Render a line series split by a threshold value, allowing different styles
+ * for parts above and below that value.
+ */
+declare function renderSplitLine(run: DataPoint[], threshold: number, ctx: RenderingContext, styles: {
+    above?: SeriesStyle;
+    below?: SeriesStyle;
+}): DrawCommand[];
+/** Render point markers for segments. */
+declare function renderMarkers$1(points: DataPoint[], ctx: RenderingContext, style: SeriesStyle, getColor: (p: DataPoint) => string): DrawCommand[];
+
+/*!
+ * 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 background grid lines (horizontal and vertical). */
+interface GridConfig {
+    /** Vertical grid lines (X-axis ticks) */
+    xTicks?: number[];
+    /** Horizontal grid lines (Y-axis ticks) */
+    yTicks?: number[];
+    /** Chart area boundaries */
+    xRange: [number, number];
+    yRange: [number, number];
+    /** Visual style */
+    stroke?: string;
+    strokeWidth?: number;
+    dashed?: boolean;
+    opacity?: number;
+}
+/** Render background grid lines (horizontal and vertical) for the chart area. */
+declare function renderGrid(config: GridConfig): DrawCommand[];
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial must have visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Configuration for rendering threshold lines, fills, and labels. */
+interface ThresholdRenderConfig {
+    /** Threshold definitions to draw. */
+    thresholds: Threshold[];
+    /** Value scale for Y-axis mapping. */
+    valueScale: LinearScale;
+    /** Pixel X range of the chart area. */
+    xRange: [number, number];
+}
+/** Render named thresholds as horizontal lines, half-plane fills, and labels. */
+declare function renderThresholds(config: ThresholdRenderConfig): DrawCommand[];
+
+/*!
+ * 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 rendering data gaps (dashed borders, empty regions, or labels). */
+interface GapRenderConfig {
+    /** Gaps to render */
+    gaps: Gap[];
+    /** Time scale for X-axis mapping */
+    timeScale: TimeScale;
+    /** Pixel Y range of the chart area */
+    yRange: [number, number];
+    /** Background fill color (default: theme.gapFill). */
+    fill?: string;
+    /** Hatch pattern for gap fill */
+    hatch?: HatchVariant;
+    /** Fill opacity (default: theme.gapFillOpacity, 0.15). */
+    fillOpacity?: number;
+    /** Border stroke color (default: theme.gapStroke). */
+    stroke?: string;
+    /** Border stroke width in pixels (default: 1). */
+    strokeWidth?: number;
+    /** Render borders as dashed lines (default true). */
+    dashed?: boolean;
+    /** Font size for gap labels in pixels (default: theme.gapFontSize). */
+    fontSize?: number;
+    /** Text color for gap labels (default: theme.gapFontColor). */
+    fontFill?: string;
+    /** Label position: 'above' (above plot), 'middle' (center of plot), or 'below' (below plot). */
+    labelBaseline?: 'above' | 'middle' | 'below';
+    /** Rotation angle for labels in degrees (default: none). */
+    labelRotate?: number;
+}
+/**
+ * Render data gaps as dashed borders, fills, or labels. Labels are positioned
+ * based on baseline: 'above' (above plot), 'middle' (center), 'below' (below plot).
+ */
+declare function renderGaps(config: GapRenderConfig): DrawCommand[];
+
+/*!
+ * 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 rendering markers (circles, vertical lines, labels). */
+interface MarkerRenderConfig {
+    /** Markers to render */
+    markers: Marker[];
+    /** Time scale for X-axis mapping */
+    timeScale: TimeScale;
+    /** Value scale for Y-axis mapping */
+    valueScale: LinearScale;
+    /** Pixel Y range of the chart area [top, bottom] */
+    yRange?: [number, number];
+}
+/** Renders markers (point circles, vertical lines, and labels) at specific time/value positions. */
+declare function renderMarkers(config: MarkerRenderConfig): DrawCommand[];
+
+/*!
+ * 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 rendering time-range highlights as colored bands. */
+interface HighlightRenderConfig {
+    /** Highlights to render */
+    highlights: Highlight[];
+    /** Time scale for X-axis mapping */
+    timeScale: TimeScale;
+    /** Pixel Y range of the chart area */
+    yRange: [number, number];
+    /** Total SVG height — needed to place a 'below' label in the bottom margin */
+    height?: number;
+}
+/** Render time-range highlights as colored bands with optional labels. */
+declare function renderHighlights(config: HighlightRenderConfig): DrawCommand[];
+
+/*!
+ * 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 rendering free-form annotations (arrow, line, rect, point, label). */
+interface AnnotationRenderConfig {
+    annotations: Annotation[];
+    timeScale: TimeScale;
+    /** Value scales per y-axis index (0 = left, 1 = right). */
+    valueScales: Map<number, LinearScale>;
+}
+/**
+ * Render free-form annotations (arrow, line, rect, point, label) given in
+ * data coordinates by projecting each point to pixels via the chart's scales.
+ */
+declare function renderAnnotations(config: AnnotationRenderConfig): DrawCommand[];
+
+/*!
+ * 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.
+ */
+/** Clipping rectangle defined by pixel coordinates and dimensions. */
+interface ClipRegion {
+    /** Clipping rectangle */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+declare class Clip {
+    #private;
+    constructor();
+    /** Add a clipping region */
+    add(region: ClipRegion): void;
+    /** Clear all clipping regions */
+    clear(): void;
+    /** Check if a point is within the clipping regions */
+    isInside(x: number, y: number): boolean;
+    /** Generate SVG clipPath element */
+    toSVGClipPath(id?: string): string;
+    /** Get current clipping regions */
+    get regions(): ClipRegion[];
+}
+
+/** Color specification for axis elements (baseline, ticks, labels). */
+interface AxisColorspec {
+    axisColor: string;
+    tickColor: string;
+    textColor: string;
+    textSize: number;
+    /** Optional stroke-width for the axis baseline + tick marks (px). Default: SVG default (1). */
+    axisWidth?: 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 time axis with automatic tick placement and formatting. */
+interface TimeAxisConfig {
+    /** Locale for i18n formatting (default: 'en-US') */
+    locale?: string;
+    /** Custom format callback override */
+    format?: (date: Date) => string;
+    /** Minimum number of ticks */
+    minTicks?: number;
+    /** Maximum number of ticks */
+    maxTicks?: number;
+    /** Pixel Y-coordinate where axis labels are drawn */
+    y?: number;
+    /** Chart area X range */
+    xRange: [number, number];
+    /** Time domain (milliseconds) */
+    domain: [number, number];
+    /** Optional axis colours */
+    colors?: AxisColorspec;
+}
+/** Tick information for time axis with computed pixel positions and labels. */
+interface TickInfo {
+    /** Timestamp of this tick */
+    time: number;
+    /** Pixel X position */
+    x: number;
+    /** Formatted label */
+    label: string;
+}
+/** Renders a time axis with automatic tick placement, anti-overlap, and i18n formatting. */
+declare class TimeAxis {
+    #private;
+    constructor(config: TimeAxisConfig);
+    get scale(): TimeScale;
+    get axisColor(): string;
+    get tickColor(): string;
+    get textColor(): string;
+    get textSize(): number;
+    /**
+     * Generate properly spaced, formatted ticks for the time axis.
+     * Applies anti-overlap: if ticks are too close, every-other is skipped.
+     */
+    generateTicks(): TickInfo[];
+    /** Pick the right date format based on the tick interval. */
+    tickLabel(time: number): string;
+    /** Remove ticks that would overlap (minimum 60px spacing). */
+    antiOverlap(ticks: TickInfo[]): TickInfo[];
+    /** Render axis baseline + tick marks as draw commands. */
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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 value axis with nice number tick placement. */
+interface ValueAxisConfig {
+    domain: [number, number];
+    range: [number, number];
+    /** Custom format callback for tick labels */
+    format?: (value: number) => string;
+    /** Number of ticks */
+    ticks?: number;
+    /** Pixel X-coordinate where axis is drawn */
+    x?: number;
+    /** Orientation: vertical (left/right) or horizontal (bottom) */
+    orientation?: "vertical" | "horizontal";
+    /** Position for vertical orientation */
+    position?: "left" | "right";
+    colors?: AxisColorspec;
+}
+/** Tick information for value axis with computed positions and formatted labels. */
+interface ValueTickInfo {
+    /** Data value at this tick */
+    value: number;
+    /** Pixel coordinate (Y for vertical, X for horizontal) */
+    position: number;
+    /** Formatted label */
+    label: string;
+}
+/** Renders a value axis with nice-number tick placement (supports vertical and horizontal). */
+declare class ValueAxis {
+    #private;
+    constructor(config: ValueAxisConfig);
+    get scale(): LinearScale;
+    get axisColor(): string;
+    get tickColor(): string;
+    get textColor(): string;
+    get textSize(): number;
+    /** Generate nicely-spaced tick values. */
+    generateTicks(): ValueTickInfo[];
+    /** Render axis as draw commands. */
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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 enum (categorical) axis. */
+interface EnumAxisConfig {
+    /** Map from enum value to display label */
+    enumMap: EnumMap;
+    /** Pixel Y range for the axis bands */
+    range: [number, number];
+    /** Pixel X position of the axis */
+    x?: number;
+    /** Show human-readable labels instead of raw values */
+    showLabels?: boolean;
+    /** Auto-assign colors per enum value */
+    autoColor?: boolean;
+    /** Which values should be treated as gaps (not rendered) */
+    gapValues?: number[];
+}
+/** Tick information for enum axis, including computed positions and colors. */
+interface EnumTickInfo {
+    value: number;
+    label: string;
+    y: number;
+    color?: string;
+    isGap: boolean;
+}
+/** Renders an enum (categorical) axis with labeled ticks and optional auto-coloring. */
+declare class EnumAxis {
+    #private;
+    constructor(config: EnumAxisConfig);
+    get scale(): BandScale;
+    /** Get all enum ticks with labels, positions, colors. */
+    generateTicks(): EnumTickInfo[];
+    /** Get color for a specific enum value. */
+    colorFor(value: number): string | undefined;
+    /** Render enum axis labels as draw commands. */
+    render(): DrawCommand[];
+    /** Map an enum value to its pixel position. */
+    map(value: number): number;
+    /** Check if a value should be treated as a gap. */
+    isGap(value: number): boolean;
+}
+
+interface BaseConfig {
+    /** SVG id prefix for elements. Generated ids: `<id>-slot-<index>`, `<id>-avg-<index>`. */
+    id?: string;
+    timeScale: TimeScale;
+}
+declare abstract class Series<T> {
+    #private;
+    static uidcnt: number;
+    constructor(config: BaseConfig, data?: T[]);
+    get id(): string;
+    get timeScale(): TimeScale;
+    get data(): T[];
+}
+
+/*!
+ * 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 rendering a continuous line chart series. */
+interface LineSeriesConfig {
+    /** Data points to render */
+    data: DataPoint[];
+    /** Time scale for X-axis mapping */
+    timeScale: TimeScale;
+    /** Value scale for Y-axis mapping */
+    valueScale: LinearScale;
+    /** Enable curve smoothing (Catmull-Rom spline) */
+    smoothing?: boolean;
+    /** Stroke color */
+    stroke?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+    /** Enable dashed line style */
+    dashed?: boolean;
+    /** Marker style for data points */
+    pointStyle?: PointStyleType;
+    /** Marker size (radius or half-width) */
+    pointSize?: number;
+    /** Maximum number of points to show markers for */
+    pointThreshold?: number;
+    /** Maximum time gap (ms) between points before breaking the line. 0 = disabled. */
+    gapThreshold?: number;
+    /** Shadow color */
+    shadowColor?: string;
+    /** Shadow blur in pixels */
+    shadowBlur?: number;
+    /** Shadow X offset in pixels */
+    shadowOffsetX?: number;
+    /** Shadow Y offset in pixels */
+    shadowOffsetY?: number;
+    /** SVG id prefix for elements. Generated ids: `<id>-line`, `<id>-marker`. */
+    id?: string;
+}
+/** Renders a continuous line chart from time-series data, with optional smoothing (Catmull-Rom spline). */
+declare class LineSeries extends Series<DataPoint> {
+    #private;
+    constructor(config: LineSeriesConfig);
+    /** Convert non-null data points to pixel coordinates (sorted by X). */
+    points(): (Point & {
+        time: number;
+    })[];
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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 rendering a step chart series. */
+interface StepSeriesConfig {
+    data: DataPoint[];
+    timeScale: TimeScale;
+    valueScale: LinearScale;
+    stroke?: string;
+    strokeWidth?: number;
+    /** SVG id prefix for elements. Generated ids: `<id>-line`. */
+    id?: string;
+}
+/** Renders a step chart from time-series data (horizontal-then-vertical transitions). */
+declare class StepSeries extends Series<DataPoint> {
+    #private;
+    constructor(config: StepSeriesConfig);
+    /**
+     * Convert (non-null) data points to step-style pixel coordinates.
+     * Each data point generates two corners (horizontal then vertical).
+     */
+    points(): Point[];
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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 rendering band charts from aggregated data. */
+interface BandSeriesConfig extends BaseConfig {
+    data: AggregatedPoint[];
+    timeScale: TimeScale;
+    valueScale: LinearScale;
+    /** Fill color for the band */
+    fill?: string;
+    /** Hatch pattern for the band fill */
+    hatch?: string;
+    /** Opacity based on count (0-1) */
+    countOpacity?: boolean;
+    /** Show average line inside band */
+    avgLine?: boolean;
+    /** Average line color */
+    avgLineColor?: string;
+    /** Width of each band in pixels (0 = auto from timeScale) */
+    bandWidth?: number;
+}
+/** Renders aggregated data as colored rectangles (bands) per time slot, with optional avg lines. */
+declare class BandSeries extends Series<AggregatedPoint> {
+    #private;
+    constructor(config: BandSeriesConfig);
+    /** Calculate opacity from count (normalized 0.2-1.0) */
+    opacity(count: number): number;
+    /** Render bands as draw commands */
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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 rendering min/max/avg lines from aggregated data. */
+interface MinMaxAvgConfig {
+    /** Aggregated points (min/max/avg per time slot). */
+    data: AggregatedPoint[];
+    /** Time scale for X-axis mapping */
+    timeScale: TimeScale;
+    /** Value scale for Y-axis mapping */
+    valueScale: LinearScale;
+    /** Stroke color for the min line (default blue) */
+    minColor?: string;
+    /** Stroke color for the max line (default red) */
+    maxColor?: string;
+    /** Stroke color for the avg line (default slate) */
+    avgColor?: string;
+    /** Render the avg line dashed (default true) */
+    avgDashed?: boolean;
+    /** Fill color for the area between avg and max (optional, use rgba/8-digit hex) */
+    fillToMax?: string;
+    /** Hatch pattern for fillToMax */
+    fillToMaxHatch?: HatchVariant;
+    /** Fill color for the area between avg and min (optional) */
+    fillToMin?: string;
+    /** Hatch pattern for fillToMin */
+    fillToMinHatch?: HatchVariant;
+    /** Catmull-Rom smoothing for the lines */
+    smoothing?: boolean;
+    /** Stroke width in px (default 2) */
+    strokeWidth?: number;
+    /** SVG id prefix for elements. Generated ids: `<id>-max`, `<id>-min`, `<id>-avg`, `<id>-fillToMax`, `<id>-fillToMin`. */
+    id?: string;
+}
+/**
+ * Draws min / max / avg of an aggregated series as three continuous lines over
+ * time, with an optional translucent fill between avg and the min/max envelope.
+ * A slot whose stats are `null` is treated as a gap and breaks the lines/fill.
+ */
+declare class MinMaxAvgSeries extends Series<AggregatedPoint> {
+    #private;
+    constructor(config: MinMaxAvgConfig);
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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 value boundary with the color used for the zone at/above it. */
+interface Zone {
+    value: number;
+    color: string;
+}
+/** Fill the area between the line and a threshold value, on one side. */
+interface ZonedFill {
+    value: number;
+    side: "above" | "below";
+    color: string;
+    hatch?: string;
+}
+/** Configuration for rendering zoned line charts with per-segment colors and optional fills. */
+interface ZonedLineConfig {
+    data: DataPoint[];
+    timeScale: TimeScale;
+    valueScale: LinearScale;
+    /** Color below the lowest zone boundary (and when there are no zones). */
+    baseColor?: string;
+    /** Zone boundaries (any order); each color applies to values ≥ its value. */
+    zones?: Zone[];
+    /** Optional fill between the line and a threshold value. */
+    fill?: ZonedFill;
+    strokeWidth?: number;
+    smoothing?: boolean;
+    /** Max time gap (ms) before the line breaks; 0 = off. */
+    gapThreshold?: number;
+    pointStyle?: PointStyleType;
+    pointSize?: number;
+    pointThreshold?: number;
+    /** SVG id prefix for elements. */
+    id?: string;
+}
+/**
+ * Line series whose colour follows value zones (boundaries → colours), with an
+ * optional translucent fill to a threshold. Breaks at `value: null` gaps and at
+ * time jumps larger than `gapThreshold`.
+ */
+declare class ZonedLineSeries extends Series<DataPoint> {
+    #private;
+    constructor(config: ZonedLineConfig);
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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.
+ */
+
+/**
+ * Horizontal annotation band below the main chart.
+ * Shares the chart time scale, renders colored time ranges with optional labels,
+ * and optionally a time axis. Standalone (not a `Series` subclass) because it
+ * does not need data iteration, gap detection, or y-scaling.
+ */
+declare class AnnotationBandSeries {
+    #private;
+    constructor(config: {
+        name: string;
+        showAxis: boolean;
+        items: AnnotationBandItem[];
+        timeScale: TimeScale;
+        background?: string;
+        hatch?: HatchVariant;
+    }, xRange: [number, number], y: number, height: number);
+    /** Render the band as colored rects with labels, optionally with a time axis. */
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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.
+ */
+
+/** Position for statistic labels on the chart. */
+type StatLabelPosition = 'start' | 'end' | 'center' | 'both';
+/** Configuration for statistics overlay (min, max, avg, median lines with labels). */
+interface StatsOverlayConfig {
+    /** Data points to compute stats from */
+    data: DataPoint[];
+    /** Value scale for Y-axis mapping */
+    valueScale: LinearScale;
+    /** Pixel X range of chart */
+    xRange: [number, number];
+    /** Which stats to show */
+    showMin?: boolean;
+    showMax?: boolean;
+    showAvg?: boolean;
+    showMedian?: boolean;
+    /** Label position */
+    labelPosition?: StatLabelPosition;
+    /** Line color */
+    lineColor?: string;
+    /** Label color */
+    labelColor?: string;
+}
+/** Renders horizontal stat lines (min/max/avg/median) with labels on the chart. */
+declare class StatsOverlay {
+    #private;
+    constructor(config: StatsOverlayConfig);
+    /** Render stats as horizontal lines with labels. */
+    render(): DrawCommand[];
+}
+
+/*!
+ * 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 formatter with i18n support.
+ * Uses Intl.DateTimeFormat with locale fallback.
+ */
+interface TimeFormatOptions {
+    /** Locale (default: 'en-US') */
+    locale?: string;
+    /** Fallback locales */
+    fallbackLocales?: string[];
+    /** Duration-based format selection */
+    autoFormat?: boolean;
+}
+declare class TimeFormatter {
+    #private;
+    constructor(opts?: TimeFormatOptions);
+    /**
+     * Format a timestamp.
+     * Auto-selects format options based on the time difference if autoFormat is enabled.
+     */
+    format(timestamp: number, opts?: Intl.DateTimeFormatOptions, referenceTime?: number): string;
+    /** Format a time range display */
+    formatRange(start: number, end: 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.
+ */
+/**
+ * Value formatter with configurable units.
+ */
+interface ValueFormatOptions {
+    /** Unit suffix (e.g., '°C', '%', 'mmHg') */
+    unit?: string;
+    /** Decimal places */
+    decimals?: number;
+    /** Compact large numbers (k, M, B) */
+    compact?: boolean;
+    /** Custom format callback */
+    custom?: (value: number) => string;
+}
+declare class ValueFormatter {
+    #private;
+    readonly _compact: boolean;
+    constructor(opts?: ValueFormatOptions);
+    /** Format a single value */
+    format(value: number): string;
+    /** Format a range of values */
+    formatRange(min: number, max: number): string;
+    /** Create a formatter for a specific unit */
+    static unit(unit: string, decimals?: number): ValueFormatter;
+    /** Temperature formatter */
+    static temperature(unit?: '°C' | '°F'): ValueFormatter;
+    /** Percentage formatter */
+    static percentage(): ValueFormatter;
+}
+
+/*!
+ * 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.
+ */
+
+/**
+ * Enum formatter: maps enum values to human-readable labels.
+ */
+interface EnumFormatterOptions {
+    /** Enum value → label mapping */
+    map?: EnumMap;
+    /** Fallback when value is not in map */
+    fallback?: (value: number) => string;
+    /** Show raw value alongside label */
+    showValue?: boolean;
+}
+declare class EnumFormatter {
+    #private;
+    constructor(opts?: EnumFormatterOptions);
+    /** Format an enum value */
+    format(value: number): string;
+    /** Check if value exists in map */
+    has(value: number): boolean;
+    /** Get all mapped labels */
+    labels(): string[];
+    /** Get all mapped values */
+    values(): number[];
+    /** Create formatter from label config strings */
+    static fromLabels(labels: string[], showValue?: boolean): EnumFormatter;
+}
+
+/*!
+ * 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.
+ */
+
+interface FormatterRegistry {
+    time: TimeFormatter;
+    value: ValueFormatter;
+    enum: EnumFormatter;
+}
+/**
+ * Formatter registry for default formatters.
+ * Provides singleton-style access to formatters.
+ */
+declare const Formatters: FormatterRegistry;
+
+/*!
+ * 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.
+ */
+
+/** Fully-resolved single line — all fields filled with defaults. */
+interface ResolvedLine {
+    color: string;
+    width: number;
+    style: LineVariant;
+    smoothing: boolean;
+    shape: "line" | "step";
+    gapThreshold: number;
+    opacity: number;
+}
+/** Fully-resolved marker — present only when a non-`none` shape is set. */
+interface ResolvedMarker {
+    type: Exclude<PointStyleType, "none">;
+    size: number;
+    stroke: string;
+    fill: string;
+    strokeWidth: number;
+    /** Hide markers when the series has more than this many samples. */
+    threshold?: number;
+}
+/** Fully-resolved shadow — present only when a non-transparent colour is set. */
+interface ResolvedShadow {
+    color: string;
+    blur: number;
+    offsetX: number;
+    offsetY: number;
+}
+/**
+ * The renderer-facing resolved style for a single raw `TimeSeries`. Every
+ * field has its theme default applied; absent layers (markers, shadow) come
+ * back as `undefined` so renderers can skip them cheaply.
+ */
+interface ResolvedSeriesStyle {
+    lines: ResolvedLine[];
+    fill?: FillSpec;
+    markers?: ResolvedMarker;
+    shadow?: ResolvedShadow;
+    gap?: GapStyle;
+    id?: string;
+}
+/** Build the resolved-line array. Empty array = no lines drawn. */
+declare function resolveLines(series: TimeSeries): ResolvedLine[];
+/** Resolve markers, or `undefined` if no marker should be drawn. */
+declare function resolveMarkers(series: TimeSeries): ResolvedMarker | undefined;
+/** Resolve shadow, or `undefined` if no shadow should be drawn. */
+declare function resolveShadow(series: TimeSeries): ResolvedShadow | undefined;
+/** Resolve gap style (pass-through). */
+declare function resolveGap(series: TimeSeries): GapStyle | undefined;
+/** Resolve the FillSpec (pass-through). */
+declare function resolveFill(series: TimeSeries): FillSpec | undefined;
+/**
+ * Resolve the full style for a raw {@link TimeSeries}. Renderers should call
+ * this once per series and read only from the returned object.
+ */
+declare function resolveSeriesStyle(series: TimeSeries): ResolvedSeriesStyle;
+
+/*!
+ * 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.
+ */
+/**
+ * Turn a free-form name into an ASCII slug usable as an `id`/CSS-class
+ * suffix. Lowercased, non-alphanumeric runs collapsed to `-`, accents
+ * stripped, trimmed, capped at 50 chars. Empty input → `'unnamed'`.
+ *
+ *   slugify('Temperatur (°C)')   → 'temperatur-c'
+ *   slugify('Signal A')          → 'signal-a'
+ *   slugify('   ')               → 'unnamed'
+ */
+declare function slugify(s: string | undefined | null): string;
+
+export { AnnotationBandSeries, type AnnotationRenderConfig, BandScale, BandSeries, type BandSeriesConfig, Clip, type ClipRegion, DrawCommand, EnumAxis, type EnumAxisConfig, EnumFormatter, type EnumFormatterOptions, type EnumTickInfo, Formatters, type GapRenderConfig, type GridConfig, type HighlightRenderConfig, LineSeries, type LineSeriesConfig, LinearScale, type MarkerRenderConfig, type MinMaxAvgConfig, MinMaxAvgSeries, type ResolvedLine, type ResolvedMarker, type ResolvedSeriesStyle, type ResolvedShadow, type StatLabelPosition, StatsOverlay, type StatsOverlayConfig, StepSeries, type StepSeriesConfig, type ThresholdRenderConfig, type TickInfo, TimeAxis, type TimeAxisConfig, type TimeFormatOptions, TimeFormatter, TimeScale, ValueAxis, type ValueAxisConfig, type ValueFormatOptions, ValueFormatter, type ValueTickInfo, type Zone, type ZonedFill, type ZonedLineConfig, ZonedLineSeries, renderAnnotations, renderArea, renderGaps, renderGrid, renderHighlights, renderLine, renderMarkers, renderMarkers$1 as renderSeriesMarkers, renderSplitLine, renderStep, renderThresholds, renderZonedArea, resolveFill, resolveGap, resolveLines, resolveMarkers, resolveSeriesStyle, resolveShadow, slugify };