ml-time-graph 1.1.0 → 1.2.0

package/README.md

@@ -86,8 +86,8 @@ Need server-side rendering of the exact same charts? There is a 1:1 Go port of t
 
 Both the TypeScript and Go libraries:
 - Process the **exact same JSON configuration schema**.
-- Generate **identical SVG structures and layout calculations**.
-- Support **multiple Y-axes** on both left and right sides (each additional axis is automatically offset horizontally by `50px` to prevent overlaps).
+- Support **multiple stacked Y-axes** on both left and right sides (with configurable pixel `offset` and automatic step offsets).
+- Ensure the **time axis baseline spans the entire plot area** with exact parity between TypeScript and Go.
 - Are continuously tested for rendering parity using shared test fixtures.
 
 ---

package/USAGE.md

@@ -2,6 +2,13 @@
 
 *[← README](README.md) · [Deutsch](README.de.md)*
 
+**Contents:** [Install](#install) · [Quick start](#quick-start) · [Series](#series) ·
+[Thresholds](#thresholds-incident-analysis) · [Fill regions](#fill-regions-the-structured-way) ·
+[Legend](#legend) · [Axes](#axes) · [Localization](#localization-i18n) · [Gaps](#gaps) ·
+[Statistic overlays](#statistic-overlays) · [Aggregation](#aggregation--helpers) ·
+[Annotations](#annotations-custom-overlays) · [Interaction & tooltips](#interaction--tooltips) ·
+[Server-side](#server-side-rendering-node) · [Package exports](#package-exports) · [Renderer](#renderer)
+
 ## Install
 
 ```bash
@@ -91,7 +98,7 @@ underneath, add `markers` for points, set `style.line: false` for points only.
 'dense-dash' | 'dash-dot' | 'dash-dot-dot' | 'loose-dash'`.
 
 A point with `value: null` (or a slot with `min/max/avg: null`) marks a **gap** — the
-line breaks there. Two y-axes are supported via `yAxisIndex: 0 | 1` on the series.
+line breaks there. Multiple y-axes are supported via `yAxisIndex: 0 | 1 | 2 | ...` on the series.
 
 ## Thresholds (incident analysis)
 
@@ -180,7 +187,7 @@ new MLTimeGraph({
       label: 'Time',
       domain: 'auto',                                       // or [tMin, tMax]
       format: (d) => d.toISOString().slice(0, 10),
-      axis:  { color: '#7c3aed' },                          // baseline + ticks
+      axis:  { color: '#7c3aed' },                          // baseline + ticks (spans full chart width)
     },
     left:  {
       label: 'Temperature (°C)',
@@ -195,6 +202,48 @@ new MLTimeGraph({
 });
 ```
 
+### Multi-Axis Layout (N Stacked Y-Axes)
+
+To support 3 or more vertical axes (or arbitrary left/right positioning), define `axes.y: YAxisConfig[]` and assign series using `yAxisIndex`:
+
+```ts
+new MLTimeGraph({
+  margin: { top: 30, right: 180, bottom: 50, left: 100 },
+  series: [
+    { name: 'RPM', yAxisIndex: 0, data: rpmData },
+    { name: 'Temp', yAxisIndex: 1, data: tempData },
+    { name: 'Vibration', yAxisIndex: 2, data: vibData },
+  ],
+  axes: {
+    x: { label: 'Time of Day' },
+    y: [
+      { position: 'left', label: 'Spindle RPM' },
+      { position: 'right', offset: 0, label: 'Temp (°C)' },
+      { position: 'right', offset: 60, label: 'Vibration (mm/s)' }, // explicit 60px offset
+    ],
+  },
+});
+```
+
+- **`position: 'left' | 'right'`**: Selects which side of the plot area the axis is anchored to.
+- **`offset?: number`**: Sets an explicit pixel offset from the chart boundary. If omitted, sequential axes step outwards by 50px automatically.
+- **Full Baseline Range**: The horizontal time-axis baseline always spans the complete chart plot area (`chartX` to `chartX + chartWidth`), even if ticks do not extend to the boundary.
+
+### Coordinate Projections & Inversion
+
+`MLTimeGraph` provides mathematical projection methods for building interactive tools (tooltips, scrubbers, crosshairs, zoom windows):
+
+```ts
+chart.renderCommands(); // initializes scale mappings
+
+// Data -> Pixel (with yAxisIndex)
+const { x, y } = chart.project(timestampMs, value, yAxisIndex);
+
+// Pixel -> Data
+const time = chart.invertTime(pixelX);
+const val  = chart.invertValue(pixelY, yAxisIndex);
+```
+
 ## Localization (i18n)
 
 The time axis is **locale-aware**: tick labels are formatted with
@@ -359,12 +408,72 @@ chart.renderCommands();
 const { x, y } = chart.project(time, value, axis);  // data → pixel
 ```
 
-## Interaction
+## Interaction & tooltips
+
+### Tooltips — `attachTooltip` (built-in)
+
+One line wires a DOM tooltip that snaps to the nearest sample per series, draws a
+"pick" ring on each matched point, and **flips across the cursor to stay inside
+the chart** (right/below in the left/top half, left/above past 50%):
+
+```ts
+import { mount, attachTooltip } from 'ml-time-graph';
+
+const chart = mount('#chart', { series });
+const detach = attachTooltip(document.querySelector('#chart')!, chart, {
+  format: (samples) =>
+    `<div>${new Date(samples[0].time).toLocaleString()}</div>` +
+    samples.map((s) => `<div>${s.series.name}: ${s.value}</div>`).join(''),
+});
+// …later:
+detach();   // removes the listeners + pick markers
+```
+
+`attachTooltip(target, chart, options?)` returns a cleanup function. The `target`
+must already contain the rendered `<svg>` (mount / render first). Each hover
+yields one `TooltipSample` per series — `{ seriesIndex, series, time, value, x, y }`.
+
+Options: `format` (HTML; default = time header + `name: value` rows),
+`snapRadius` (px, default ∞), `className` (default `mlc-tooltip`), and
+`showPicks` / `pickRadius` / `picksClassName` for the markers. Style the box via
+the `.mlc-tooltip` CSS class — **don't set `transform`**; placement (incl. the
+flip) is computed in JS.
+
+### Zoom / pan
+
+Zoom, pan and minimap are **not** baked into the chart. Map pixels back to data
+with `chart.invertTime(px)` / `chart.invertValue(py, axisIndex)` and wire the
+interaction in your app, or pull the optional `Zoom` / `Minimap` helpers from the
+[`ml-time-graph/interaction`](#package-exports) subpath. See the demo gallery's
+"Fridge" (range slider) and "Interaction" pages.
+
+## Server-side rendering (Node)
+
+`SVGRenderer` needs no DOM, so the same code runs in Node — set explicit
+`width`/`height` (there's no element to measure) and write the string out:
+
+```ts
+import { MLTimeGraph, SVGRenderer } from 'ml-time-graph';
+import { writeFileSync } from 'node:fs';
+
+const chart = new MLTimeGraph({ width: 800, height: 400, series });
+const { content } = new SVGRenderer().render(chart.renderCommands());
+writeFileSync('chart.svg', content);
+```
+
+Useful for report generation, PDF embedding (via a headless browser), and email
+attachments. For a Node-free backend, the Go port
+[`go-time-graph`](https://gitlab.com/mlc0911/mlctimegraph/-/tree/main/go-time-graph)
+renders the same JSON config to identical SVG.
+
+## Package exports
 
-Zoom/pan and tooltips are intentionally **not** baked into the chart. Map pixels to
-data with `chart.invertTime(px)` / `chart.invertValue(py, axisIndex)` and build the
-interaction in your app — see the demo gallery's "Fridge" (range slider) and
-"Interaction" (tooltip) pages.
+| Import | Contents |
+| :--- | :--- |
+| `ml-time-graph` | The rendering API — `mount`, `MLTimeGraph`, `SVGRenderer`, `attachTooltip`, and all option/data types. |
+| `ml-time-graph/analyze` | Statistics companion — `aggregateBySlot`, `downsample`, `detectGaps`, `mkt` / `rollingMkt`, `stdDev`, `StatsAggregator`, … (see [Aggregation](#aggregation--helpers)). |
+| `ml-time-graph/interaction` | Optional interaction primitives — `Zoom`, `Minimap`, `Tooltip` (lower-level than `attachTooltip`). |
+| `ml-time-graph/internals` | Building blocks for **custom renderers** — the abstract `Renderer`, free render-functions, scales, axis classes, the `DrawCommand` model. |
 
 ## Renderer
 

package/dist/analyze/index.d.ts

@@ -147,7 +147,7 @@ declare function aggregateBySlot(data: DataPoint[], mode?: "hourly" | "daily" |
 declare function createAggr(time: number, values: number[]): AggregatedPoint;
 /**
  * Detect gaps in time-series data (autoDetect).
- * Gibt alle Zeitenrücken zurück wo das Zeitintervall > minGapMs ist.
+ * Returns all time gaps where the interval is > minGapMs.
  */
 declare function detectGaps(data: DataPoint[], minGapMs?: number): DetectedGap[];
 interface LongTermInsight {
@@ -350,6 +350,13 @@ interface NamedSeries {
     /** Time-ordered samples. `value: null` is treated as a gap and ignored. */
     data: DataPoint[];
 }
+
+/*!
+ * 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.
+ */
+
 /**
  * Per-timestamp summary of a multi-sensor recording.
  * `delta = max - min` is the room's "spatial spread" at that instant.
@@ -382,6 +389,13 @@ interface SpatialPoint {
  * silently skipped for that point.
  */
 declare function spatialDelta(sensors: NamedSeries[]): SpatialPoint[];
+
+/*!
+ * 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.
+ */
+
 /** Aggregate statistics for one sensor across the full observation window. */
 interface SensorStat {
     name: string;

package/dist/analyze/index.js

@@ -1,4 +1,4 @@
-var H=class{static interpolateDataPoint(n,i,t){return {time:n.time+t*(i.time-n.time),value:(n.value??0)+t*((i.value??0)-(n.value??0))}}static interpolateAggregatedPoint(n,i,t){let u=(e,l)=>e!==null&&l!==null?e+t*(l-e):null;return {time:n.time+t*(i.time-n.time),min:u(n.min,i.min),max:u(n.max,i.max),avg:u(n.avg,i.avg),count:Math.round(n.count+t*(i.count-n.count))}}static getRuns(n,i,t=0){let u=[...n].sort((r,o)=>r.time-o.time),e=[],l=[],a=null;for(let r of u){let o=i(r),m=t>0&&a&&r.time-a.time>t;(o||m)&&l.length&&(e.push(l),l=[]),o||l.push(r),a=r;}return l.length&&e.push(l),e}static splitByBoundaries(n,i,t,u){if(n.length===0)return [];if(i.length===0)return [{data:n,zoneIndex:0}];let e=[...i].sort((o,m)=>o-m),l=[],a=o=>{let m=0;for(let s=0;s<e.length&&o>=e[s];s++)m=s+1;return m},r=[n[0]];for(let o=1;o<n.length;o++){let m=n[o-1],s=n[o],h=t(m),g=t(s),d;g>h?d=e.filter(c=>c>h&&c<=g):g<h?d=e.filter(c=>c>=g&&c<h).reverse():d=[];for(let c of d){let p=(c-h)/(g-h),x=u(m,s,p);r.push(x),l.push({data:r,zoneIndex:a((h+c)/2)}),r=[x];}r.push(s);}if(r.length>0){let o=t(r[0]),m=t(r[r.length-1]);l.push({data:r,zoneIndex:a((o+m)/2)});}return l}static splitByThreshold(n,i,t,u){let e=this.splitByBoundaries(n,[i],t,u),l={above:[],below:[]};for(let a of e)a.zoneIndex===0?l.below.push(a.data):l.above.push(a.data);return l}},L={pharma_cold:{limitLow:2,limitHigh:8,activationEnergy:83144},pharma_ambient:{limitLow:15,limitHigh:25,activationEnergy:83144},blood:{limitLow:2,limitHigh:6,activationEnergy:83144},food_chilled:{limitLow:0,limitHigh:4},frozen:{limitLow:-40,limitHigh:-18}},T=8.314462618,w=273.15;function N(n,i,t,u=1){let e=i.filter(f=>f.value!==null&&f.value!==void 0&&!isNaN(f.value)).map(f=>f.value);if(!e.length)return {time:n,min:null,max:null,avg:null,mkt:null,deltaMkt:null,stdDev:null,minutesAboveHigh:t?0:null,minutesBelowLow:t?0:null,count:0};let l=Math.min(...e),a=Math.max(...e),r=e.reduce((f,v)=>f+v,0)/e.length,o=t?0:null,m=t?0:null;if(t)for(let f=0;f<i.length;f++){let v=i[f];if(v.value!==null&&v.value!==void 0){let b=i[f+1],M=(b?b.time-v.time:0)/(1e3*60);v.value>t.limitHigh&&(o+=M),v.value<t.limitLow&&(m+=M);}}let s=0,h=0,g=(t?.activationEnergy??83144)/T;for(let f of e){s+=Math.pow(f-r,2);let v=f+w;h+=Math.exp(-g/v);}let d=s/e.length,c=Math.sqrt(d),p=null,x=null;if(e.length>=u){let f=h/e.length,v=g/-Math.log(f);p=Number((v-w).toFixed(2)),x=Number((p-r).toFixed(2));}return {time:n,min:Number(l.toFixed(2)),max:Number(a.toFixed(2)),avg:Number(r.toFixed(2)),mkt:p,deltaMkt:x,stdDev:Number(c.toFixed(2)),minutesAboveHigh:o!==null?Number(o.toFixed(1)):null,minutesBelowLow:m!==null?Number(m.toFixed(1)):null,count:e.length}}function D(n,i="hourly",t,u,e=1){if(!n.length)return [];let l=i==="hourly"?36e5:i==="daily"?864e5:t??3600*1e3,a=[...n].sort((s,h)=>s.time-h.time),r=[],o=a[0].time,m=[];for(let s of a){for(;s.time-o>=l;)r.push(N(o,m,u,e)),o+=l,m=[];m.push(s);}return r.push(N(o,m,u,e)),r}function A(n,i){let t=Math.min(...i),u=Math.max(...i),e=i.reduce((l,a)=>l+a,0)/i.length;return {time:n,min:t,max:u,avg:e,count:i.length}}function B(n,i=6e4){if(n.length<2)return [];let t=[...n].sort((e,l)=>e.time-l.time),u=[];for(let e=1;e<t.length;e++)t[e].time-t[e-1].time>i&&u.push({startTime:t[e-1].time,endTime:t[e].time});return u}function I(n){let i=[],t=0,u=0,e=0,l=0;for(let a of n)a.count>0&&(e++,a.minutesAboveHigh&&(t+=a.minutesAboveHigh),a.stdDev&&a.stdDev>u&&(u=a.stdDev),a.deltaMkt&&a.deltaMkt>2&&l++);return e===0?[]:(t>120&&i.push({type:"critical",message:`Kritische Gesamtbelastung: Das Produkt war im gesamten Zeitraum insgesamt ${Math.round(t)} Minuten zu warm.`,metric:"Total Excursion Time"}),l>e*.15&&i.push({type:"warning",message:"H\xE4ufige thermische Schocks erkannt. Die kinetische Temperatur weicht oft stark vom Schnitt ab (m\xF6gliche regelm\xE4\xDFige T\xFCr\xF6ffnungen).",metric:"Delta MKT Instability"}),u>4&&i.push({type:"warning",message:`Hohe Instabilit\xE4t gemessen. Die maximale Standardabweichung lag bei ${u}\xB0C. Das K\xFChlsystem regelt unsauber.`,metric:"Standard Deviation Peak"}),i)}function z(n,i){if(n.length<=i)return n;let t=[],u=Math.ceil(n.length/i);t.push(n[0]);for(let e=1;e<n.length;e+=u)t.push(n[Math.min(e,n.length-1)]);return t}function C(n,i="hourly",t){let u={limitLow:t.low,limitHigh:t.high,activationEnergy:t.activationEnergy};return D(n,i,t.interval,u,t.minCountForMkt??1)}var P=class{static compute(n){let i=n.map(r=>r.value).filter(r=>r!==null).sort((r,o)=>r-o);if(i.length===0)return {min:NaN,max:NaN,avg:NaN,mean:NaN,median:NaN,stdDev:NaN,count:0};let t=i.length,u=i.reduce((r,o)=>r+o,0)/t,e=t%2===1?i[Math.floor(t/2)]:(i[t/2-1]+i[t/2])/2,l=i.reduce((r,o)=>r+Math.pow(o-u,2),0)/t,a=Math.sqrt(l);return {min:i[0],max:i[t-1],avg:u,mean:u,median:e,stdDev:a,count:t}}static computeInRange(n,i,t){let u=n.filter(e=>e.time>=i&&e.time<=t);return this.compute(u)}};function _(n,i){let t=typeof n=="number"?n:n.mean,u=typeof n=="number"?i??NaN:n.stdDev;return !Number.isFinite(t)||!Number.isFinite(u)||t===0?null:Math.abs(u/t)*100}var R=83144;function F(n,i=83144){let t=i/8.314,u=0,e=0;for(let a of n)a!==null&&(u+=Math.exp(-t/(a+273.15)),e++);if(e===0)return null;let l=u/e;return t/-Math.log(l)-273.15}function q(n,i,t=83144){let u=new Array(n.length),e=0;for(let l=0;l<n.length;l++){let a=n[l].time,r=a-i;for(;e<l&&n[e].time<r;)e++;let o=n.slice(e,l+1).map(s=>s.value),m=F(o,t);u[l]={time:a,value:m,synthetic:true};}return u}function k(n){let i=0,t=0;for(let l of n)l!==null&&(i+=l,t++);if(t===0)return null;let u=i/t,e=0;for(let l of n){if(l===null)continue;let a=l-u;e+=a*a;}return Math.sqrt(e/t)}function S(n){let i=0,t=0;for(let l of n)l!==null&&(i+=l,t++);if(t<2)return null;let u=i/t,e=0;for(let l of n){if(l===null)continue;let a=l-u;e+=a*a;}return Math.sqrt(e/(t-1))}function K(n,i,t=false){let u=new Array(n.length),e=0,l=t?S:k;for(let a=0;a<n.length;a++){let r=n[a].time,o=r-i;for(;e<a&&n[e].time<o;)e++;let m=n.slice(e,a+1).map(h=>h.value),s=l(m);u[a]={time:r,value:s,synthetic:true};}return u}function G(n,i){let{high:t,low:u}=i,e={msAboveHigh:0,msBelowLow:0,globalMax:null,globalMin:null,excursions:[]},l=null;for(let a=0;a<n.length;a++){let r=n[a];if(r.value===null){l&&(e.excursions.push(l),l=null);continue}(e.globalMax===null||r.value>e.globalMax)&&(e.globalMax=r.value),(e.globalMin===null||r.value<e.globalMin)&&(e.globalMin=r.value);let o=t!==void 0&&r.value>t,m=u!==void 0&&r.value<u,s=o?"above":m?"below":null,h=n[a-1];if(h&&h.value!==null&&s!==null){let g=r.time-h.time;s==="above"?e.msAboveHigh+=g:e.msBelowLow+=g;}if(s===null){l&&(e.excursions.push(l),l=null);continue}l&&l.side===s?(l.endTime=r.time,l.durationMs=l.endTime-l.startTime,(s==="above"&&r.value>l.extremum||s==="below"&&r.value<l.extremum)&&(l.extremum=r.value)):(l&&e.excursions.push(l),l={startTime:r.time,endTime:r.time,side:s,extremum:r.value,durationMs:0});}return l&&e.excursions.push(l),e}function O(n){if(n.length===0)return [];let i=new Map;for(let u of n)for(let e of u.data){if(e.value===null)continue;let l=i.get(e.time);l||(l=[],i.set(e.time,l)),l.push({name:u.name,value:e.value});}let t=[];for(let u of [...i.keys()].sort((e,l)=>e-l)){let e=i.get(u);if(e.length===0){t.push({time:u,min:null,max:null,delta:null,minSensor:null,maxSensor:null});continue}let l=e[0],a=e[0];for(let r=1;r<e.length;r++)e[r].value<l.value&&(l=e[r]),e[r].value>a.value&&(a=e[r]);t.push({time:u,min:l.value,max:a.value,delta:e.length<2?null:a.value-l.value,minSensor:l.name,maxSensor:a.name});}return t}function U(n){let i=[];for(let e of n){let l=0,a=0,r=1/0,o=-1/0;for(let m of e.data)m.value!==null&&(l+=m.value,a++,m.value<r&&(r=m.value),m.value>o&&(o=m.value));a!==0&&i.push({name:e.name,mean:l/a,min:r,max:o,count:a});}if(i.length===0)return {sensors:[],hottest:null,coldest:null,meanDelta:null};let t=i[0],u=i[0];for(let e=1;e<i.length;e++)i[e].mean>t.mean&&(t=i[e]),i[e].mean<u.mean&&(u=i[e]);return {sensors:i,hottest:t,coldest:u,meanDelta:t.mean-u.mean}}function y(n){let i=0,t=0,u=0,e=0,l=0;for(let m of n)m.value!==null&&(i++,t+=m.time,u+=m.value,e+=m.time*m.value,l+=m.time*m.time);if(i<2)return null;let a=i*l-t*t;if(a===0)return null;let r=(i*e-t*u)/a,o=(u-r*t)/i;return {slope:r,intercept:o,n:i}}function E(n,i){if(n.length===0)return null;let t=n[n.length-1].time,u=t-i,e=n.filter(l=>l.time>=u&&l.time<=t);return y(e)}function V(n,i){let t=[],u=0;for(let e=0;e<n.length;e++){let l=n[e].time,a=l-i;for(;u<n.length&&n[u].time<a;)u++;let r=y(n.slice(u,e+1));t.push({time:l,fit:r});}return t}function W(n,i,t={}){let u=t.lookbackMs??9e5,e=t.side??"either";if(n.length===0)return null;let l=n[n.length-1];if(l.value===null)return null;let a=E(n,u);if(!a||a.slope===0)return null;let r=a.slope>0&&l.value<i,o=a.slope<0&&l.value>i;if(e==="above"&&!r||e==="below"&&!o||e==="either"&&!r&&!o)return null;let m=(i-a.intercept)/a.slope,s=m-l.time;return s<=0?null:{msUntil:s,eta:m,fit:a,currentValue:l.value}}function Y(n,i={}){let t=i.refTempCelsius??121.11,u=i.zValueKelvin??10,e=0;for(let l=0;l<n.length-1;l++){let a=n[l],r=n[l+1];if(a.value===null||r.value===null)continue;let o=(r.time-a.time)/6e4;if(o<=0)continue;let m=Math.pow(10,(a.value-t)/u),s=Math.pow(10,(r.value-t)/u);e+=(m+s)/2*o;}return e}/*!
+var H=class{static interpolateDataPoint(n,i,t){return {time:n.time+t*(i.time-n.time),value:(n.value??0)+t*((i.value??0)-(n.value??0))}}static interpolateAggregatedPoint(n,i,t){let u=(e,l)=>e!==null&&l!==null?e+t*(l-e):null;return {time:n.time+t*(i.time-n.time),min:u(n.min,i.min),max:u(n.max,i.max),avg:u(n.avg,i.avg),count:Math.round(n.count+t*(i.count-n.count))}}static getRuns(n,i,t=0){let u=[...n].sort((r,o)=>r.time-o.time),e=[],l=[],a=null;for(let r of u){let o=i(r),m=t>0&&a&&r.time-a.time>t;(o||m)&&l.length&&(e.push(l),l=[]),o||l.push(r),a=r;}return l.length&&e.push(l),e}static splitByBoundaries(n,i,t,u){if(n.length===0)return [];if(i.length===0)return [{data:n,zoneIndex:0}];let e=[...i].sort((o,m)=>o-m),l=[],a=o=>{let m=0;for(let s=0;s<e.length&&o>=e[s];s++)m=s+1;return m},r=[n[0]];for(let o=1;o<n.length;o++){let m=n[o-1],s=n[o],h=t(m),g=t(s),d;g>h?d=e.filter(c=>c>h&&c<=g):g<h?d=e.filter(c=>c>=g&&c<h).reverse():d=[];for(let c of d){let p=(c-h)/(g-h),x=u(m,s,p);r.push(x),l.push({data:r,zoneIndex:a((h+c)/2)}),r=[x];}r.push(s);}if(r.length>0){let o=t(r[0]),m=t(r[r.length-1]);l.push({data:r,zoneIndex:a((o+m)/2)});}return l}static splitByThreshold(n,i,t,u){let e=this.splitByBoundaries(n,[i],t,u),l={above:[],below:[]};for(let a of e)a.zoneIndex===0?l.below.push(a.data):l.above.push(a.data);return l}},S={pharma_cold:{limitLow:2,limitHigh:8,activationEnergy:83144},pharma_ambient:{limitLow:15,limitHigh:25,activationEnergy:83144},blood:{limitLow:2,limitHigh:6,activationEnergy:83144},food_chilled:{limitLow:0,limitHigh:4},frozen:{limitLow:-40,limitHigh:-18}},T=8.314462618,w=273.15;function y(n,i,t,u=1){let e=i.filter(f=>f.value!==null&&f.value!==void 0&&!isNaN(f.value)).map(f=>f.value);if(!e.length)return {time:n,min:null,max:null,avg:null,mkt:null,deltaMkt:null,stdDev:null,minutesAboveHigh:t?0:null,minutesBelowLow:t?0:null,count:0};let l=Math.min(...e),a=Math.max(...e),r=e.reduce((f,v)=>f+v,0)/e.length,o=t?0:null,m=t?0:null;if(t)for(let f=0;f<i.length;f++){let v=i[f];if(v.value!==null&&v.value!==void 0){let b=i[f+1],M=(b?b.time-v.time:0)/(1e3*60);v.value>t.limitHigh&&(o+=M),v.value<t.limitLow&&(m+=M);}}let s=0,h=0,g=(t?.activationEnergy??83144)/T;for(let f of e){s+=Math.pow(f-r,2);let v=f+w;h+=Math.exp(-g/v);}let d=s/e.length,c=Math.sqrt(d),p=null,x=null;if(e.length>=u){let f=h/e.length,v=g/-Math.log(f);p=Number((v-w).toFixed(2)),x=Number((p-r).toFixed(2));}return {time:n,min:Number(l.toFixed(2)),max:Number(a.toFixed(2)),avg:Number(r.toFixed(2)),mkt:p,deltaMkt:x,stdDev:Number(c.toFixed(2)),minutesAboveHigh:o!==null?Number(o.toFixed(1)):null,minutesBelowLow:m!==null?Number(m.toFixed(1)):null,count:e.length}}function D(n,i="hourly",t,u,e=1){if(!n.length)return [];let l=i==="hourly"?36e5:i==="daily"?864e5:t??3600*1e3,a=[...n].sort((s,h)=>s.time-h.time),r=[],o=a[0].time,m=[];for(let s of a){for(;s.time-o>=l;)r.push(y(o,m,u,e)),o+=l,m=[];m.push(s);}return r.push(y(o,m,u,e)),r}function E(n,i){let t=Math.min(...i),u=Math.max(...i),e=i.reduce((l,a)=>l+a,0)/i.length;return {time:n,min:t,max:u,avg:e,count:i.length}}function B(n,i=6e4){if(n.length<2)return [];let t=[...n].sort((e,l)=>e.time-l.time),u=[];for(let e=1;e<t.length;e++)t[e].time-t[e-1].time>i&&u.push({startTime:t[e-1].time,endTime:t[e].time});return u}function z(n){let i=[],t=0,u=0,e=0,l=0;for(let a of n)a.count>0&&(e++,a.minutesAboveHigh&&(t+=a.minutesAboveHigh),a.stdDev&&a.stdDev>u&&(u=a.stdDev),a.deltaMkt&&a.deltaMkt>2&&l++);return e===0?[]:(t>120&&i.push({type:"critical",message:`Kritische Gesamtbelastung: Das Produkt war im gesamten Zeitraum insgesamt ${Math.round(t)} Minuten zu warm.`,metric:"Total Excursion Time"}),l>e*.15&&i.push({type:"warning",message:"Frequent thermal shocks detected. The kinetic temperature deviates strongly from the average (possible regular door openings).",metric:"Delta MKT Instability"}),u>4&&i.push({type:"warning",message:`High instability measured. Maximum standard deviation was ${u}\xB0C. The cooling system controls imprecisely.`,metric:"Standard Deviation Peak"}),i)}function I(n,i){if(n.length<=i)return n;let t=[],u=Math.ceil(n.length/i);t.push(n[0]);for(let e=1;e<n.length;e+=u)t.push(n[Math.min(e,n.length-1)]);return t}function C(n,i="hourly",t){let u={limitLow:t.low,limitHigh:t.high,activationEnergy:t.activationEnergy};return D(n,i,t.interval,u,t.minCountForMkt??1)}var P=class{static compute(n){let i=n.map(r=>r.value).filter(r=>r!==null).sort((r,o)=>r-o);if(i.length===0)return {min:NaN,max:NaN,avg:NaN,mean:NaN,median:NaN,stdDev:NaN,count:0};let t=i.length,u=i.reduce((r,o)=>r+o,0)/t,e=t%2===1?i[Math.floor(t/2)]:(i[t/2-1]+i[t/2])/2,l=i.reduce((r,o)=>r+Math.pow(o-u,2),0)/t,a=Math.sqrt(l);return {min:i[0],max:i[t-1],avg:u,mean:u,median:e,stdDev:a,count:t}}static computeInRange(n,i,t){let u=n.filter(e=>e.time>=i&&e.time<=t);return this.compute(u)}};function _(n,i){let t=typeof n=="number"?n:n.mean,u=typeof n=="number"?i??NaN:n.stdDev;return !Number.isFinite(t)||!Number.isFinite(u)||t===0?null:Math.abs(u/t)*100}var q=83144;function k(n,i=83144){let t=i/8.314,u=0,e=0;for(let a of n)a!==null&&(u+=Math.exp(-t/(a+273.15)),e++);if(e===0)return null;let l=u/e;return t/-Math.log(l)-273.15}function R(n,i,t=83144){let u=new Array(n.length),e=0;for(let l=0;l<n.length;l++){let a=n[l].time,r=a-i;for(;e<l&&n[e].time<r;)e++;let o=n.slice(e,l+1).map(s=>s.value),m=k(o,t);u[l]={time:a,value:m,synthetic:true};}return u}function F(n){let i=0,t=0;for(let l of n)l!==null&&(i+=l,t++);if(t===0)return null;let u=i/t,e=0;for(let l of n){if(l===null)continue;let a=l-u;e+=a*a;}return Math.sqrt(e/t)}function L(n){let i=0,t=0;for(let l of n)l!==null&&(i+=l,t++);if(t<2)return null;let u=i/t,e=0;for(let l of n){if(l===null)continue;let a=l-u;e+=a*a;}return Math.sqrt(e/(t-1))}function G(n,i,t=false){let u=new Array(n.length),e=0,l=t?L:F;for(let a=0;a<n.length;a++){let r=n[a].time,o=r-i;for(;e<a&&n[e].time<o;)e++;let m=n.slice(e,a+1).map(h=>h.value),s=l(m);u[a]={time:r,value:s,synthetic:true};}return u}function K(n,i){let{high:t,low:u}=i,e={msAboveHigh:0,msBelowLow:0,globalMax:null,globalMin:null,excursions:[]},l=null;for(let a=0;a<n.length;a++){let r=n[a];if(r.value===null){l&&(e.excursions.push(l),l=null);continue}(e.globalMax===null||r.value>e.globalMax)&&(e.globalMax=r.value),(e.globalMin===null||r.value<e.globalMin)&&(e.globalMin=r.value);let o=t!==void 0&&r.value>t,m=u!==void 0&&r.value<u,s=o?"above":m?"below":null,h=n[a-1];if(h&&h.value!==null&&s!==null){let g=r.time-h.time;s==="above"?e.msAboveHigh+=g:e.msBelowLow+=g;}if(s===null){l&&(e.excursions.push(l),l=null);continue}l&&l.side===s?(l.endTime=r.time,l.durationMs=l.endTime-l.startTime,(s==="above"&&r.value>l.extremum||s==="below"&&r.value<l.extremum)&&(l.extremum=r.value)):(l&&e.excursions.push(l),l={startTime:r.time,endTime:r.time,side:s,extremum:r.value,durationMs:0});}return l&&e.excursions.push(l),e}function O(n){if(n.length===0)return [];let i=new Map;for(let u of n)for(let e of u.data){if(e.value===null)continue;let l=i.get(e.time);l||(l=[],i.set(e.time,l)),l.push({name:u.name,value:e.value});}let t=[];for(let u of [...i.keys()].sort((e,l)=>e-l)){let e=i.get(u);if(e.length===0){t.push({time:u,min:null,max:null,delta:null,minSensor:null,maxSensor:null});continue}let l=e[0],a=e[0];for(let r=1;r<e.length;r++)e[r].value<l.value&&(l=e[r]),e[r].value>a.value&&(a=e[r]);t.push({time:u,min:l.value,max:a.value,delta:e.length<2?null:a.value-l.value,minSensor:l.name,maxSensor:a.name});}return t}function U(n){let i=[];for(let e of n){let l=0,a=0,r=1/0,o=-1/0;for(let m of e.data)m.value!==null&&(l+=m.value,a++,m.value<r&&(r=m.value),m.value>o&&(o=m.value));a!==0&&i.push({name:e.name,mean:l/a,min:r,max:o,count:a});}if(i.length===0)return {sensors:[],hottest:null,coldest:null,meanDelta:null};let t=i[0],u=i[0];for(let e=1;e<i.length;e++)i[e].mean>t.mean&&(t=i[e]),i[e].mean<u.mean&&(u=i[e]);return {sensors:i,hottest:t,coldest:u,meanDelta:t.mean-u.mean}}function N(n){let i=0,t=0,u=0,e=0,l=0;for(let m of n)m.value!==null&&(i++,t+=m.time,u+=m.value,e+=m.time*m.value,l+=m.time*m.time);if(i<2)return null;let a=i*l-t*t;if(a===0)return null;let r=(i*e-t*u)/a,o=(u-r*t)/i;return {slope:r,intercept:o,n:i}}function A(n,i){if(n.length===0)return null;let t=n[n.length-1].time,u=t-i,e=n.filter(l=>l.time>=u&&l.time<=t);return N(e)}function V(n,i){let t=[],u=0;for(let e=0;e<n.length;e++){let l=n[e].time,a=l-i;for(;u<n.length&&n[u].time<a;)u++;let r=N(n.slice(u,e+1));t.push({time:l,fit:r});}return t}function W(n,i,t={}){let u=t.lookbackMs??9e5,e=t.side??"either";if(n.length===0)return null;let l=n[n.length-1];if(l.value===null)return null;let a=A(n,u);if(!a||a.slope===0)return null;let r=a.slope>0&&l.value<i,o=a.slope<0&&l.value>i;if(e==="above"&&!r||e==="below"&&!o||e==="either"&&!r&&!o)return null;let m=(i-a.intercept)/a.slope,s=m-l.time;return s<=0?null:{msUntil:s,eta:m,fit:a,currentValue:l.value}}function Y(n,i={}){let t=i.refTempCelsius??121.11,u=i.zValueKelvin??10,e=0;for(let l=0;l<n.length-1;l++){let a=n[l],r=n[l+1];if(a.value===null||r.value===null)continue;let o=(r.time-a.time)/6e4;if(o<=0)continue;let m=Math.pow(10,(a.value-t)/u),s=Math.pow(10,(r.value-t)/u);e+=(m+s)/2*o;}return e}/*!
 * 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.
@@ -12,4 +12,4 @@ var H=class{static interpolateDataPoint(n,i,t){return {time:n.time+t*(i.time-n.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.
- */export{R as DEFAULT_ACTIVATION_ENERGY,L as PRODUCT_PROFILES,H as SeriesProcessor,P as StatsAggregator,D as aggregateBySlot,C as aggregateWithStats,I as analyzeLongTermTrends,G as computeLimitExcursions,A as createAggr,E as currentTrend,B as detectGaps,z as downsample,Y as f0Sterilization,U as hotColdSpots,y as linearFit,F as mkt,W as predictTimeToThreshold,q as rollingMkt,K as rollingStdDev,V as rollingTrend,S as sampleStdDev,O as spatialDelta,k as stdDev,_ as varianceCoefficient};
+ */export{q as DEFAULT_ACTIVATION_ENERGY,S as PRODUCT_PROFILES,H as SeriesProcessor,P as StatsAggregator,D as aggregateBySlot,C as aggregateWithStats,z as analyzeLongTermTrends,K as computeLimitExcursions,E as createAggr,A as currentTrend,B as detectGaps,I as downsample,Y as f0Sterilization,U as hotColdSpots,N as linearFit,k as mkt,W as predictTimeToThreshold,R as rollingMkt,G as rollingStdDev,V as rollingTrend,L as sampleStdDev,O as spatialDelta,F as stdDev,_ as varianceCoefficient};

package/dist/index.d.ts

@@ -1,6 +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-DDdMtPrB.js';
-import { U as LineVariant, g as AnySeries, aa as Threshold, P as Highlight, I as Gap, N as GapsConfig, d as Annotation, e as AnnotationBandConfig, o as DrawCommand, ad as TimeScale, V as LinearScale, O as HatchVariant, f as AnnotationBandItem, _ as PointStyleType, ac as ThresholdLabelPosition, a5 as SeriesStyle, G as FillSpec, af as TimeSeries, A as AggregatedPoint, a as AggregatedSeries, k as DataPoint } from './scale-DcFBNLdU.js';
-export { b as AggregationConfig, c as AggregationMode, l as DataPointRef, E as EnumMap, F as FillBound, x as FillDirectionType, y as FillRegion, z as FillSide, H as FillStyle, J as GapConfig, K as GapLabel, L as GapRegion, M as GapStyle, R as LineDashStyle, T as LineStyle, X as MarkerStyle, a2 as SensorType, a3 as SeriesOverlay, a4 as SeriesOverlayKind, a6 as SeriesType, a7 as ShadowStyle, ab as ThresholdLabelConfig } from './scale-DcFBNLdU.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-C_t250fG.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, a5 as SeriesStyle, G as FillSpec, af as TimeSeries, O as HatchVariant, ac as ThresholdLabelPosition, _ as PointStyleType, f as AnnotationBandItem, A as AggregatedPoint, a as AggregatedSeries, k as DataPoint } from './scale-DFyECKZq.js';
+export { b as AggregationConfig, c as AggregationMode, l as DataPointRef, E as EnumMap, F as FillBound, x as FillDirectionType, y as FillRegion, z as FillSide, H as FillStyle, J as GapConfig, K as GapLabel, L as GapRegion, M as GapStyle, R as LineDashStyle, T as LineStyle, X as MarkerStyle, a2 as SensorType, a3 as SeriesOverlay, a4 as SeriesOverlayKind, a6 as SeriesType, a7 as ShadowStyle, ab as ThresholdLabelConfig } from './scale-DFyECKZq.js';
 
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
@@ -47,6 +47,8 @@ interface AxisLabelsStyle {
 interface YAxisConfig {
     /** Position is 'left' or 'right' to determine placement side. Defaults to 'left'. */
     position?: "left" | "right";
+    /** Optional explicit horizontal pixel offset from chart edge (defaults to index * 50px). */
+    offset?: number;
     /** Rotated label drawn next to the axis. */
     label?: string;
     /** Override the value domain. `'auto'` lets the chart compute it from data. */
@@ -82,6 +84,7 @@ interface XAxisConfig {
 /**
  * Top-level axes container on {@link MLTimeGraphOptions}.
  * `left` and `right` correspond to `yAxisIndex: 0` and `yAxisIndex: 1` series.
+ * Additional axes can be defined in the `y` array, with indices mapping to series via `yAxisIndex`.
  */
 interface AxesConfig {
     x?: XAxisConfig;
@@ -105,7 +108,7 @@ interface Margin {
     left: number;
 }
 /** Legend placement position — inside or outside the chart area. */
-type LegendPosition = 'inside-right' | 'inside-left' | 'outside-right' | 'outside-left' | 'separate';
+type LegendPosition = "inside-right" | "inside-left" | "outside-right" | "outside-left" | "separate";
 interface LegendOptions {
     /** Show the legend (default false). */
     show?: boolean;
@@ -294,7 +297,8 @@ interface TooltipOptions {
  * 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:
+ * Style the tooltip via CSS. Do NOT set `transform` — placement (incl. the
+ * flip that keeps the box inside the chart) is computed in JS via `transform`:
  *
  * ```css
  * .mlc-tooltip {
@@ -306,7 +310,6 @@ interface TooltipOptions {
  *   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; font-weight: 600; }
@@ -465,6 +468,13 @@ declare class GraphBuilder {
      */
     mount(target: HTMLElement | string): 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.
+ */
+
 /**
  * TimeSeriesBuilder simplifies constructing raw TimeSeries datasets.
  */
@@ -473,6 +483,11 @@ declare class TimeSeriesBuilder {
     constructor(name: string);
     /** Appends a value-point to the series. */
     addPoint(time: number, value: number | null): this;
+    /** Sets the data points array for the series. */
+    setData(points: Array<{
+        time: number;
+        value: number | null;
+    }>): this;
     /** Appends an array of data points directly to the series. */
     addPoints(points: Array<{
         time: number;
@@ -482,6 +497,10 @@ declare class TimeSeriesBuilder {
     addFloats(times: number[], values: Array<number | null>): this;
     /** Appends a null point (signaling gaps/offline state). */
     addNullPoint(time: number): this;
+    /** Assigns the target Y-axis index (0=left, 1=right, 2+=multi-axis). */
+    setYAxisIndex(index: number): this;
+    /** Shortcut to apply a primary stroke color to the series line. */
+    setColor(color: string): this;
     /** Assigns the visual styles configuration. */
     setStyle(style: SeriesStyle): this;
     /** Shortcut to apply custom stroke styling (color, width, dash style). */
@@ -497,6 +516,13 @@ declare class TimeSeriesBuilder {
     /** Compiles and returns the TimeSeries object. */
     build(): TimeSeries;
 }
+
+/*!
+ * 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.
+ */
+
 /**
  * ThresholdBuilder simplifies constructing value boundaries.
  */
@@ -518,6 +544,13 @@ declare class ThresholdBuilder {
     /** Compiles and returns the Threshold object. */
     build(): Threshold;
 }
+
+/*!
+ * 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.
+ */
+
 /**
  * MarkerBuilder simplifies constructing vertical pins/markers.
  */
@@ -539,6 +572,13 @@ declare class MarkerBuilder {
     /** Compiles and returns the Marker object. */
     build(): Marker;
 }
+
+/*!
+ * 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.
+ */
+
 /**
  * HighlightBuilder simplifies constructing highlighted time bands.
  */
@@ -558,6 +598,13 @@ declare class HighlightBuilder {
     /** Compiles and returns the Highlight object. */
     build(): Highlight;
 }
+
+/*!
+ * 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.
+ */
+
 /**
  * AnnotationBuilder simplifies constructing free-form annotations.
  */
@@ -607,6 +654,13 @@ declare class AnnotationBuilder {
     /** Compiles and returns the Annotation object. */
     build(): Annotation;
 }
+
+/*!
+ * 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.
+ */
+
 /**
  * AnnotationBandBuilder simplifies constructing annotation bands below the chart.
  */
@@ -645,7 +699,7 @@ declare class AnnotationBandItemBuilder {
     /** Sets the border stroke width. */
     setStrokeWidth(w: number): this;
     /** Sets the text label and optional label formatting fields. */
-    setLabel(lbl: string, fontSize?: number, fill?: string, baseline?: 'top' | 'middle' | 'bottom'): this;
+    setLabel(lbl: string, fontSize?: number, fill?: string, baseline?: "top" | "middle" | "bottom"): this;
     /** Compiles and returns the AnnotationBandItem object. */
     build(): AnnotationBandItem;
 }
@@ -661,7 +715,11 @@ declare class SVGRenderer extends Renderer {
     constructor(options?: {
         width?: number | string;
         height?: number | string;
+        /** Optional solid background colour, drawn as a full-size rect (e.g. "white"). */
+        background?: string;
     });
+    /** Set a solid background colour, drawn as a full-size rect behind the chart. */
+    setBackgroundColor(color: string): void;
     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)". */