ml-time-graph 1.0.0

package/LICENSE

@@ -0,0 +1,32 @@
+MLTimeGraph License (MIT with Attribution)
+Copyright (c) 2026 Michael Lechner
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom
+the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. Attribution. Any product or service that uses the Software, including
+   commercial and closed-source products, must give clearly visible credit to
+   the author "Michael Lechner" in a location reasonably accessible to end
+   users (for example: product documentation, an "About" / credits screen, a
+   legal-notices page, or a comparable place).
+
+3. Commercial license (attribution waiver). Organizations that do not wish to
+   display the attribution required by Section 2 may obtain a separate
+   commercial license that waives this requirement. Such a license is available
+   from the author on request.
+   Contact: mlcgo.eu@michael-lechner.de
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MKT_AGGREGATE.md

@@ -0,0 +1,154 @@
+# Dokumentation: Kinetische Temperaturaggregation (`aggregateBySlot`)
+
+Dieses Modul bietet eine mathematische Kernfunktion zur zeitlichen Aggregation von Temperatur-Loggerdaten. Neben klassischen statistischen Werten (`min`, `max`, `avg`, `stdDev`) berechnet die Funktion die **Mean Kinetic Temperature (MKT)** sowie die präzise Dauer von Grenzwertverletzungen in Minuten.
+
+Die Funktion ist vollständig **entkoppelt**, besitzt kein inhärentes Wissen über spezifische Produkte (Blut, Pharma, Lebensmittel) und wird rein über mathematische Parameter gesteuert.
+
+---
+
+## 1. Was ist die Mean Kinetic Temperature (MKT)?
+
+Die MKT ist eine Methode zur Bewertung von Temperaturschwankungen bei der Lagerung und dem Transport von temperaturempfindlichen Gütern. Im Gegensatz zum arithmetischen Mittelwert (`avg`) gewichtet die MKT **höhere Temperaturen exponentiell stärker**. Dies bildet das reale biologische und chemische Degradationsverhalten (Verderb) von Produkten ab, da chemische Reaktionen bei Wärme beschleunigt ablaufen (Arrhenius-Gleichung).
+
+### Mathematische Formel (nach USP <1079.2>)
+
+$$T_{K} = \frac{\frac{\Delta H}{R}}{-\ln\left(\frac{e^{-\frac{\Delta H}{R \cdot T_1}} + e^{-\frac{\Delta H}{R \cdot T_2}} + \dots + e^{-\frac{\Delta H}{R \cdot T_n}}}{n}\right)}$$
+
+*   **$T_K$**: Mittlere kinetische Temperatur in Kelvin.
+*   **$\Delta H$**: Aktivierungsenergie. Der globale Standard für Pharma- und GDP-Audits beträgt **$83.144\text{ kJ/mol}$** ($83144\text{ J/mol}$).
+*   **$R$**: Universelle Gaskonstante ($8.31446\text{ J/(mol}\cdot\text{K)}$).
+*   **$T_n$**: Gemessene Temperatur zum Zeitpunkt $n$ in Kelvin.
+*   **$n$**: Anzahl der gültigen Messwerte im Intervall.
+
+---
+
+## 2. Datenstrukturen & Interfaces
+
+### Eingangsdaten (`DataPoint`)
+Die Rohdaten erlauben explizit `null`-Werte (z. B. bei temporärem Sensorausfall).
+
+```typescript
+export interface DataPoint {
+  time: number;        // Unix-Zeitstempel in Millisekunden
+  value: number | null; // Temperaturwert in °C oder null
+}
+```
+
+### Konfiguration (`AggregationThresholds`)
+Ermöglicht die Übergabe dynamischer Grenzwerte zur Bestimmung der Abweichungsminuten.
+
+```typescript
+export interface AggregationThresholds {
+  limitLow: number;          // Unterer Grenzwert in °C
+  limitHigh: number;         // Oberer Grenzwert in °C
+  activationEnergy?: number; // Optional: Aktivierungsenergie in J/mol (Standard: 83144.0)
+}
+```
+
+### Ausgangsdaten (`StatsAggregatedPoint`)
+
+`aggregateBySlot()` mit `thresholds`-Parameter liefert
+`StatsAggregatedPoint[]` — eine Intersection aus `MktPoint`,
+`StdDevPoint` und `LimitStatsPoint`. Die Basis-`AggregatedPoint` trägt
+nur die statistischen Pflichtfelder; alles MKT/σ/Limit-spezifische lebt
+auf den spezialisierten Untertypen, sodass User unfallfrei zwischen
+"reine min/max/avg"-Aggregation und "voll dekoriertem" Slot
+unterscheiden können.
+
+```typescript
+export interface AggregatedPoint {
+  time: number;                  // Startzeitpunkt des Slots in ms
+  min: number | null;            // Niedrigste Temperatur im Slot
+  max: number | null;            // Höchste Temperatur im Slot
+  avg: number | null;            // Arithmetischer Mittelwert
+  count: number;                 // Anzahl valider Messwerte
+}
+
+export interface MktPoint extends AggregatedPoint {
+  mkt: number | null;            // Mean Kinetic Temperature in °C
+  deltaMkt?: number | null;      // Delta zur Vor-Slot-MKT (optional)
+}
+
+export interface StdDevPoint extends AggregatedPoint {
+  stdDev: number | null;         // Standardabweichung
+}
+
+export interface LimitStatsPoint extends AggregatedPoint {
+  minutesAboveHigh?: number | null;
+  minutesBelowLow?: number | null;
+}
+
+export type StatsAggregatedPoint = MktPoint & StdDevPoint & LimitStatsPoint;
+```
+
+---
+
+## 3. Kern-Features des Algorithmus
+
+1. **Umgang mit Lücken & Ausfällen (`null`-Werte):**
+   * `null`-Werte in den Rohdaten werden vor der mathematischen Berechnung strikt herausgefiltert. Sie verfälschen weder Minimum, Maximum noch die MKT-Exponentialsumme.
+   * Ein Slot, der *ausschließlich* aus `null`-Daten besteht, bleibt im Ausgabe-Array als Platzhalter erhalten (`count: 0`, alle Werte sind `null`), um Zeitleisten-Lücken in Diagrammen zu verhindern.
+2. **Präzise Zeitsynchronität (Feste Slots):**
+   * Die Funktion verwendet ein festes Intervallgitter. Unabhängig davon, wann Datenpunkte eintreffen, springt das Raster präzise um die exakte Intervall-Länge (z. B. stündlich).
+3. **MKT-Stabilitätsschutz (`minCountForMkt`):**
+   * Die MKT benötigt eine statistisch relevante Anzahl an Messwerten. Über einen Parameter kann definiert werden, ab wie vielen validen Punkten im Slot die MKT berechnet wird. Wird die Schwelle unterschritten, wird `mkt` sicher auf `null` gesetzt, anstatt mathematische Artefakte zu erzeugen.
+4. **Präzise Abweichungsdauer (Dauer in Minuten):**
+   * Anstatt nur Datenpunkte zu zählen, berechnet die Funktion die reale zeitliche Differenz zwischen aufeinanderfolgenden Loggereinträgen. Dadurch werden unregelmäßige Datenaufzeichnungen (z. B. Event-basierte Logger) exakt in Minuten erfasst.
+
+---
+
+## 4. Integration & Nutzung im System
+
+Da die Kernfunktion mathematisch dumm gehalten ist, werden die branchenspezifischen Vorgaben (Pharma, Blut, Lebensmittel) **außerhalb** über die Konfigurationsschicht verwaltet.
+
+### Typische Produkt-Grenzwerte im Überblick
+
+
+| Produktkategorie | Unteres Limit (`limitLow`) | Oberes Limit (`limitHigh`) | Aktivierungsenergie ($\Delta H$) |
+| :--- | :--- | :--- | :--- |
+| **Pharma (Kühlkette)** | $+2.0^\circ\text{C}$ | $+8.0^\circ\text{C}$ | $83144\text{ J/mol}$ (USP Standard) |
+| **Pharma (Raumtemperatur)** | $+15.0^\circ\text{C}$ | $+25.0^\circ\text{C}$ | $83144\text{ J/mol}$ (USP Standard) |
+| **Blutkonserven** | $+2.0^\circ\text{C}$ | $+6.0^\circ\text{C}$ | $83144\text{ J/mol}$ (Standard-Anwendung) |
+| **Lebensmittel (Frische)** | $0.0^\circ\text{C}$ | $+4.0^\circ\text{C}$ | *MKT irrelevant / entfällt meist* |
+| **Tiefkühlkost** | $-40.0^\circ\text{C}$ | $-18.0^\circ\text{C}$ | *MKT irrelevant / entfällt meist* |
+
+### Code-Beispiele zur Verwendung
+
+#### Beispiel 1: Standard-Aggregation stündlich ohne Limits
+Es werden nur die Basis-Statistiken und die MKT berechnet. Die Alarmminuten bleiben `null`.
+```typescript
+import { aggregateBySlot } from "ml-time-graph/analyze";
+
+const hourlyStats = aggregateBySlot(rawLoggerData, "hourly");
+```
+
+#### Beispiel 2: Aggregation für Blutkonserven (Tägliches Intervall)
+Hier werden die Grenzwerte injiziert. Die Funktion berechnet automatisch, wie viele Minuten die Blutkonserven außerhalb der erlaubten $2^\circ\text{C} - 6^\circ\text{C}$ lagen.
+```typescript
+const bloodThresholds = {
+  limitLow: 2.0,
+  limitHigh: 6.0
+  // activationEnergy wird weggelassen -> nutzt automatisch internen 83144 J/mol Fallback
+};
+
+const dailyBloodReport = aggregateBySlot(
+  rawLoggerData, 
+  "daily", 
+  undefined, // customInterval
+  bloodThresholds,
+  12 // MKT erst berechnen, wenn mindestens 12 gültige Werte im Tag liegen
+);
+```
+
+#### Beispiel 3: Spezial-Laborwert (Custom Aktivierungsenergie)
+Sollte ein Audit für ein bestimmtes biologisches Plasma-Protein eine abweichende Aktivierungsenergie vorschreiben, kann diese direkt mitgegeben werden:
+```typescript
+const customLabThresholds = {
+  limitLow: 1.0,
+  limitHigh: 4.5,
+  activationEnergy: 65000.0 // 65 kJ/mol statt 83.144 kJ/mol
+};
+
+const labReport = aggregateBySlot(rawLoggerData, "hourly", undefined, customLabThresholds);
+```
+

package/README.de.md

@@ -0,0 +1,154 @@
+# 📈 MLTimeGraph
+
+*[English](README.md) · Deutsch*
+
+**TypeScript-Library für die grafische Darstellung von Messwerten** — Zeitreihen
+schnell und unkompliziert aufbereiten, mit Fokus auf Reporting und Incident-Analyse.
+
+> Voll typisiert · i18n-aware · DOM-freier SVG-Renderer (Browser & serverseitig) · keine Laufzeit-Abhängigkeiten · ESM-only
+
+## Installation
+
+```bash
+npm install ml-time-graph     # oder: pnpm add / yarn add
+```
+
+Voraussetzung: **Node 18+**. Die Library ist **ESM-only** — funktioniert
+out of the box mit jedem modernen Bundler (Vite, Rollup, esbuild,
+Webpack 5+, Next.js, Astro, …) und in Node-ESM (`"type": "module"` in
+deiner `package.json`, oder `.mjs`-Dateien).
+
+Vier Subpath-Imports:
+
+| Import | Zweck |
+| --- | --- |
+| `ml-time-graph` | User-API — `mount`, `MLTimeGraph`, `SVGRenderer`, `attachTooltip`, alle Input- + Style-Typen |
+| `ml-time-graph/analyze` | Aggregation + Statistik (`aggregateBySlot`, `rollingMkt`, `rollingStdDev`, `downsample`, …) |
+| `ml-time-graph/interaction` | Optionale Widgets (`Zoom`, `Minimap`, `Tooltip`) |
+| `ml-time-graph/internals` | Building Blocks für eigene Renderer (freie Render-Funktionen, Scales, Axis-Klassen, `DrawCommand`-Modell, …) |
+
+### Reines HTML / CDN
+
+Kein Build-Schritt? Hol's direkt von einem ESM-CDN, der npm proxyed:
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import { mount } from 'https://esm.sh/ml-time-graph@1';
+  // oder: 'https://cdn.jsdelivr.net/npm/ml-time-graph@1/+esm'
+
+  mount('#chart', {
+    series: [{ name: 'Temp', data: [/* … */] }],
+  });
+</script>
+```
+
+Pinne eine Major-Version (`@1`), damit dich Breaking Changes nicht überraschen.
+
+## Quickstart
+
+```ts
+import { mount } from 'ml-time-graph';
+
+mount('#chart', {
+  series: [{
+    name: 'Temperatur',
+    style: { line: { color: '#ef4444' } },
+    data: [
+      { time: Date.UTC(2026, 0, 1, 0), value: 18.2 },
+      { time: Date.UTC(2026, 0, 1, 1), value: 19.1 },
+    ],
+  }],
+  tooltip: { show: true },   // optionaler Hover-Tooltip mit Visual-Picks
+});
+```
+
+📖 **Nutzung & API → [USAGE.md](USAGE.md)** *(englisch)*
+
+## Galerie
+
+<p align="center">
+  <a href="ex1.svg"><img src="ex1.svg" alt="Linie mit Zonen-Färbung und Threshold-Fills" width="300"></a>
+  <a href="ex2.svg"><img src="ex2.svg" alt="Multi-Zonen-Hatch-Fills" width="300"></a>
+  <a href="ex3.svg"><img src="ex3.svg" alt="stdDevBand + movingMkt-Overlays auf einem Sensorstrom" width="300"></a>
+</p>
+
+Typische Sensor-Darstellung (links), Multi-Zonen-Schraffuren für
+Incident-Reports (Mitte), Sensorstrom mit Statistik-Overlays (rechts:
+±2σ-Band + 12-h-MKT) — alles dieselbe Library, alle in der
+Demo-Galerie zu sehen (`pnpm dev`).
+
+---
+
+## Warum schon wieder eine neue Library?
+
+Alle Libraries, die ich in der Vergangenheit professionell genutzt habe, haben
+irgendwann ihr Lizenzmodell von *frei* auf *kostenpflichtig* umgestellt. Das wird
+zum Problem, sobald ein Wechsel nicht möglich ist: Man muss „alte" Libraries
+plötzlich ersetzen oder selbst weiterpflegen (z. B. an aktuelle Browser-Entwicklungen
+anpassen).
+
+Ich brauche keine 100 Chart Typen.
+
+MLTimeGraph ist **nicht** dazu gedacht, tausend verschiedene Chart-Typen
+abzudecken. Der Fokus liegt darauf, **Messwerte — also Zeit + Daten — schnell und
+unkompliziert grafisch aufzubereiten**. Ein besonderes Augenmerk liegt auf der
+**Incident-Analyse**: etwa wenn Sensoren zur Überwachung von Geräten eingesetzt
+werden und die nachträgliche Auswertung entscheidend ist.
+
+## Ziele
+
+- ✅ **Keine Browser-Abhängigkeit** — das Rendering ist vom DOM entkoppelt (SVG-String, im Browser und serverseitig)
+- ✅ **Voll typisiert** — durchgängig TypeScript
+- ✅ **Einfache Integration** in bestehende Projekte
+- ✅ **i18n-aware** — lokalisierte Zeitachsen und Formatierung
+- ✅ **Einfache, aber umfangreiche Konfiguration** — Farben, Linienstärken, Styles
+- ✅ Typische Darstellungen für Messwerte:
+  - Markierung von Bereichen (Highlights)
+  - Thresholds (Bänder, Linien, Flächen)
+  - min / max / avg-Darstellungen
+  - Incident-Analysen — markante Ereignisse und Werte markieren
+
+## Nicht-Ziele
+
+- ❌ **High Performance** — für den Hauptanwendungsfall (Reporting, Analyse) nicht notwendig
+- ❌ **Volle Interaktivität** — Zoom/Pan ja, aber in Grenzen
+- ❌ GPU-Performance-Optimierungen o. Ä.
+
+## Ausblick / in Überlegung
+
+- Möglichkeiten der „Live"-Darstellung
+- Einfache Anbindung von Backends (woher kommen meine Daten?)
+- svelte wrapper
+
+## Demos & Entwicklung
+
+```bash
+pnpm install
+pnpm dev          # startet die Demo-Galerie (Vite)
+```
+
+| Script | Zweck |
+| --- | --- |
+| `pnpm dev` | Demo-Galerie lokal starten |
+| `pnpm test` | Test-Suite (Vitest) |
+| `pnpm typecheck` | Library typprüfen |
+| `pnpm typecheck:demos` | Demos typprüfen |
+| `pnpm build` | Library bauen (ESM-Bundle + Types) |
+
+## Lizenz
+
+© 2026 Michael Lechner — **MIT mit Attribution-Klausel** (siehe [LICENSE](LICENSE)).
+
+Nutzung, Änderung und Verbreitung — **auch kommerziell und in Closed-Source-Produkten** —
+sind kostenlos erlaubt, sofern der Autor **„Michael Lechner" sichtbar genannt** wird
+(z. B. in Doku, Impressum/Rechtliches oder einem About-/Credits-Bereich) und der
+Copyright-Hinweis im Quellcode erhalten bleibt.
+
+**Ohne Nennung:** Unternehmen, die die Attribution nicht zeigen möchten, können eine
+**kommerzielle Lizenz auf Anfrage** erhalten, die diese Pflicht aufhebt — Kontakt: ‹mlcgo.eu@michael-lechner.de›.
+
+---
+
+<sub>Das Projekt diente ursprünglich als Test für Crush-Development mit Ollama +
+neuem LLM — bestanden 😉, brauchte aber doch einige Nacharbeit.</sub>

package/README.md

@@ -0,0 +1,152 @@
+# 📈 MLTimeGraph
+
+*English · [Deutsch](README.de.md)*
+
+**A TypeScript library for visualizing measurement data** — turn time series into
+clear, readable charts quickly, with a focus on reporting and incident analysis.
+
+> Fully typed · i18n-aware · DOM-free SVG output (browser & server) · zero runtime dependencies · ESM-only
+
+## Install
+
+```bash
+npm install ml-time-graph     # or: pnpm add / yarn add
+```
+
+Requires **Node 18+**. The library is **ESM-only** — works out of the
+box in any modern bundler (Vite, Rollup, esbuild, Webpack 5+, Next.js,
+Astro, …) and in Node ESM (`"type": "module"` in your `package.json`,
+or `.mjs` files).
+
+Four subpath imports:
+
+| Import | Purpose |
+| --- | --- |
+| `ml-time-graph` | User API — `mount`, `MLTimeGraph`, `SVGRenderer`, `attachTooltip`, all input + style types |
+| `ml-time-graph/analyze` | Aggregation + statistics (`aggregateBySlot`, `rollingMkt`, `rollingStdDev`, `downsample`, …) |
+| `ml-time-graph/interaction` | Optional widgets (`Zoom`, `Minimap`, `Tooltip`) |
+| `ml-time-graph/internals` | Building blocks for custom renderers (free render-functions, scales, axis classes, `DrawCommand` model, …) |
+
+### Plain HTML / CDN
+
+No build step? Pull it straight from an ESM CDN that proxies npm:
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import { mount } from 'https://esm.sh/ml-time-graph@1';
+  // or: 'https://cdn.jsdelivr.net/npm/ml-time-graph@1/+esm'
+
+  mount('#chart', {
+    series: [{ name: 'Temp', data: [/* … */] }],
+  });
+</script>
+```
+
+Pin a major version (`@1`) to avoid surprise breaking changes.
+
+## Quickstart
+
+```ts
+import { mount } from 'ml-time-graph';
+
+mount('#chart', {
+  series: [{
+    name: 'Temperature',
+    style: { line: { color: '#ef4444' } },
+    data: [
+      { time: Date.UTC(2026, 0, 1, 0), value: 18.2 },
+      { time: Date.UTC(2026, 0, 1, 1), value: 19.1 },
+    ],
+  }],
+  tooltip: { show: true },   // optional hover tooltip with visual picks
+});
+```
+
+📖 **Usage & API → [USAGE.md](USAGE.md)**
+
+## Gallery
+
+<p align="center">
+  <a href="ex1.svg"><img src="ex1.svg" alt="Line chart with zoned colouring + threshold fills" width="300"></a>
+  <a href="ex2.svg"><img src="ex2.svg" alt="Hatched multi-zone threshold fills" width="300"></a>
+  <a href="ex3.svg"><img src="ex3.svg" alt="stdDevBand + movingMkt overlays on a sensor stream" width="300"></a>
+</p>
+
+A typical sensor visualisation (left), multi-zone hatched fills for
+incident-style reports (center), and a sensor stream with statistic
+overlays (right: ±2σ band + 12 h MKT) — all rendered with the same
+library, all live in the demo gallery (`pnpm dev`).
+
+---
+
+## Why another chart library?
+
+Every charting library I relied on professionally eventually switched its license
+from *free* to *paid* — a real problem when you can't follow that move: you end up
+having to replace "old" libraries or maintain them yourself (e.g. keeping up with
+browser changes).
+
+I don't need a hundred chart types.
+
+MLTimeGraph is **not** meant to cover a thousand chart types. The focus is on turning
+**measurements — time + values — into clear charts quickly**, with particular
+attention to **incident analysis**: e.g. when sensors monitor equipment and the
+after-the-fact evaluation is what matters.
+
+## Goals
+
+- ✅ **No browser dependency** — rendering is decoupled from the DOM (SVG string, in the browser and server-side)
+- ✅ **Fully typed** — TypeScript throughout
+- ✅ **Easy integration** into existing projects
+- ✅ **i18n-aware** — localized time axes and formatting
+- ✅ **Simple yet thorough configuration** — colors, line widths, styles
+- ✅ Typical measurement visualizations:
+  - region highlights
+  - thresholds (lines, fills, zones)
+  - min / max / avg displays
+  - incident analysis — mark notable events and values
+
+## Non-goals
+
+- ❌ **High performance** — not needed for the main use case (reporting, analysis)
+- ❌ **Full interactivity** — zoom/pan yes, but within limits
+- ❌ GPU performance optimizations and the like
+
+## Outlook / under consideration
+
+- "Live" rendering options
+- Simple backend integration (where does my data come from?)
+- Svelte wrapper
+
+## Demos & development
+
+```bash
+pnpm install
+pnpm dev          # start the demo gallery (Vite)
+```
+
+| Script | Purpose |
+| --- | --- |
+| `pnpm dev` | run the demo gallery locally |
+| `pnpm test` | test suite (Vitest) |
+| `pnpm typecheck` | type-check the library |
+| `pnpm typecheck:demos` | type-check the demos |
+| `pnpm build` | build the library (ESM bundle + types) |
+
+## License
+
+© 2026 Michael Lechner — **MIT with an Attribution clause** (see [LICENSE](LICENSE)).
+
+Use, modification and distribution — **including in commercial and closed-source
+products** — are free of charge, provided the author **"Michael Lechner" is visibly
+credited** (e.g. in documentation, a legal-notices page, or an About/credits screen)
+and the copyright notice is retained in the source.
+
+**Without attribution:** organizations that prefer not to display the attribution can
+obtain a **commercial license on request** that waives it — contact: ‹mlcgo.eu@michael-lechner.de›.
+
+---
+
+<sub>Originally a test of Crush development with Ollama + a new LLM — passed 😉, but it
+did need some rework.</sub>