ml-time-graph 1.3.3 → 1.4.0

package/SKILLS.md

@@ -0,0 +1,183 @@
+# SKILLS.md — Agent Quick Start for `ml-time-graph`
+
+MLTimeGraph is a TypeScript library for visualizing any time-series measurement data (telemetry, physical sensors, system metrics, logs, finance, laboratory or process measurements). Its standout capability is rich contextual annotation — turning raw curves into explanatory records with free-form annotations (arrows, labels, callout rects in data coordinates), time-range highlights, status/phase bands, and threshold zones. It has a single defining architectural property: it generates SVG as a pure string without touching the DOM — the exact same call runs identically in the browser and on the server.
+
+For the exhaustive reference, see [USAGE.md](USAGE.md) next to this file.
+
+## Shortest Path to a Visible Chart
+
+```ts
+import { mount } from 'ml-time-graph';
+
+mount('#chart', {
+  width: 800,
+  height: 400,
+  series: [
+    {
+      name: 'Temperature',
+      data: [
+        { time: 1704067200000, value: 21.5 },
+        { time: 1704070800000, value: 22.8 },
+        { time: 1704074400000, value: 20.3 },
+      ],
+      style: { line: { color: '#ef4444' } },
+    },
+  ],
+});
+```
+
+## When to Use What
+
+- `mount(target, options)`: The declarative browser shortcut when a DOM element or selector exists — measures container width, renders SVG, and injects markup in one call.
+- `new MLTimeGraph(options)`: The core headless engine when working with options objects directly — use for Node.js SSR, headless testing, or custom render pipelines.
+- Builders (`GraphBuilder`, etc.): The fluent, imperative chaining API — use when assembling charts dynamically across conditional branches.
+- Go port (`go-time-graph`): The 1:1 server-side Go implementation (`gitlab.com/mlc0911/mlctimegraph/go-time-graph`) — use when rendering charts in Go backends or microservices without a Node runtime.
+
+## Package Entry Points
+
+- `ml-time-graph`: Core chart rendering API — `mount`, `MLTimeGraph`, `SVGRenderer`, `GraphBuilder`, `attachTooltip`, types, and legend helpers (`resolveDash`, `drawMarker`).
+- `ml-time-graph/analyze`: Pure-math statistics companion — `aggregateBySlot`, `downsample` (LTTB), `detectGaps`, `rollingMkt`, `rollingStdDev`, `computeLimitExcursions`, `StatsAggregator`.
+- `ml-time-graph/interaction`: Headless interaction primitives — `Zoom`, `Minimap`, and coordinate-based interaction state management.
+- `ml-time-graph/internals`: Low-level building blocks for custom renderers — `DrawCommand` model, base `Renderer`, layout engine, scales, and axis renderers.
+
+## Common Tasks
+
+### Multiple Series & Multi-Axis
+Map series to vertical axes via `yAxisIndex`:
+```ts
+mount('#chart', {
+  margin: { top: 20, right: 80, bottom: 40, left: 60 },
+  series: [
+    { name: 'Temp', data: tempData, yAxisIndex: 0, style: { line: { color: '#ef4444' } } },
+    { name: 'Humidity', data: humData, yAxisIndex: 1, style: { line: { color: '#3b82f6', style: 'dashed' } } },
+  ],
+  axes: {
+    left: { label: 'Temperature (°C)' },
+    right: { label: 'Humidity (%)' },
+  },
+});
+```
+
+### Thresholds & Zone Colouring
+Define thresholds once and reference them by name to colour lines or zones:
+```ts
+mount('#chart', {
+  thresholds: [
+    { name: 'warn', value: 25, color: '#f59e0b', line: 'dashed', label: 'Warning' },
+    { name: 'crit', value: 30, color: '#ef4444', line: 'solid', label: 'Critical' },
+  ],
+  series: [{ name: 'Temp', data: tempData, colorByThresholds: ['warn', 'crit'] }],
+});
+```
+
+### Filled Areas Between Curve and Threshold
+Use `style.fill.regions` with bounds (`from`, `to`, `side`, optional `hatch`):
+```ts
+style: {
+  fill: {
+    regions: [
+      { from: { threshold: 'warn' }, to: 'series', side: 'above', fill: { color: '#f59e0b33', hatch: 'classic-diagonal' } },
+      { from: { threshold: 'crit' }, to: 'series', side: 'above', fill: '#ef444444' },
+    ],
+  },
+}
+```
+
+### Annotations & Region Highlights
+Enrich charts with domain context: vertical time-span highlights across the plot, free-form annotations in data coordinates (which automatically scale through zoom/resize), and status bands below:
+```ts
+mount('#chart', {
+  series,
+  // Vertical time-range highlight behind the data:
+  highlights: [
+    { startTime: t1, endTime: t2, label: 'Calibration Phase', color: '#3b82f6', opacity: 0.15 },
+  ],
+  // Overlays anchored in data coordinates (time/value) tracking zoom & resize:
+  annotations: [
+    { type: 'arrow', from: { time: t1, value: 20 }, to: { time: t2, value: 35 }, color: '#ef4444' },
+    { type: 'label', at: { time: t2, value: 35 }, text: 'Pressure Spike', dy: -10 },
+    { type: 'rect', from: { time: t1, value: 15 }, to: { time: t2, value: 25 }, fill: '#10b98122' },
+  ],
+  // Horizontal status/phase bands below the plot (sharing the time axis):
+  annotationBands: [
+    {
+      name: 'Operating State',
+      height: 20,
+      items: [
+        { startTime: t1, endTime: t2, label: 'Running', fill: '#22c55e44' },
+        { startTime: t2, endTime: t3, label: 'Standby', fill: '#eab30844' },
+      ],
+    },
+  ],
+});
+```
+
+### Data Gaps
+`value: null` marks missing data and breaks the line. Connect with a bridge or render gap spans:
+```ts
+series: [{
+  name: 'Sensor',
+  data: [{ time: 1704067200000, value: 20 }, { time: 1704070800000, value: null }, { time: 1704074400000, value: 25 }],
+  style: {
+    line: { color: '#3b82f6' },
+    gap: { display: 'bridge_line', bridge: { color: '#94a3b8', width: 1.5, style: 'dotted' } },
+  },
+}]
+```
+
+### Markers
+Render sample markers on curves or standalone timestamp event lines:
+```ts
+series: [{
+  name: 'Sensor',
+  data: sensorData,
+  style: { markers: { type: 'circle', size: 3, stroke: '#3b82f6', fill: '#ffffff', threshold: 100 } },
+}],
+markers: [
+  { time: 1704070800000, value: 25, label: 'Peak event', color: '#ef4444', lineStyle: 'to-value' },
+]
+```
+
+### Axes & Margins
+The layout engine cannot measure rendered text. Always allocate sufficient margins for labels:
+```ts
+margin: { top: 20, right: 80, bottom: 40, left: 60 },
+axes: {
+  x: { label: 'Time', format: (d: Date) => d.toISOString().slice(11, 16) },
+  left: { label: 'Temperature (°C)', format: (v: number) => `${v.toFixed(1)} °C` },
+  right: { label: 'Humidity (%)', format: (v: number) => `${v.toFixed(0)} %` },
+}
+```
+
+### Tooltips & Interactive Projections
+Attach DOM tooltips or use pixel/data coordinate projections:
+```ts
+// Built-in DOM tooltip:
+const chart = mount('#chart', { series, tooltip: { show: true } });
+
+// Interactive coordinate projections (crosshairs, zoom, scrubbers):
+chart.renderCommands();
+const timeMs = chart.invertTime(pixelX);
+const value = chart.invertValue(pixelY, yAxisIndex);
+const { x, y } = chart.project(timeMs, value, yAxisIndex);
+```
+
+### Server-Side Rendering (Node.js)
+Generate pure SVG strings without browser dependencies:
+```ts
+import { MLTimeGraph, SVGRenderer } from 'ml-time-graph';
+import * as fs from 'node:fs';
+
+const chart = new MLTimeGraph({ width: 800, height: 400, series });
+const { content } = new SVGRenderer().render(chart.renderCommands());
+fs.writeFileSync('chart.svg', content);
+```
+
+## Traps (Read Before Coding)
+
+- **Timestamps are numbers, not Date objects:** `time` is always milliseconds since Unix epoch (`number`). Passing a `Date` object fails typechecking or evaluates to `NaN`.
+- **Labels are not measured (fixed margins):** The renderer has no DOM and cannot compute text bounding boxes. Margins default to `{ top: 20, right: 20, bottom: 40, left: 60 }`. If you add a right Y-axis or formatted units (e.g. `120.5 °C`), `right: 20` will clip the labels against the SVG edge. A clipped number is a wrong number, not an incomplete one (`120` clipped to `20`). Always set `margin.right` explicitly (e.g. 70–90 px) when using right axes.
+- **`resolveDash()` vs `getLineStyle()`:** `dashed` and `dotted` predate the scalable dash table and keep fixed SVG patterns (`"4,4"` and `"2,4"`) in the renderer for backwards compatibility. `getLineStyle()` returns the scalable table (`"6, 4"` for width 2). Anyone rendering custom legend swatches must call `resolveDash(variant, width)` so the swatch matches what is actually drawn.
+- **Marker suppression at threshold:** `style.markers.threshold` (and default `theme.pointThreshold = 100`) hides point markers when series sample count exceeds it to prevent visual crowding. Crucially, `chart.legendItems()` also omits the `marker` property when points are suppressed, because a symbol in the legend missing from the curve states something untrue.
+- **Built-in legend is static SVG:** Built-in legends (`inside-right`, etc.) are non-interactive SVG elements. For interactive series toggling or HTML layout below the chart, use `legend: { position: 'separate' }` and render HTML buttons from `chart.legendItems()` using `drawMarker()` and `SVGRenderer` or `resolveDash()`.
+- **Hatch lines adapt to fill colour:** Hatch patterns inherit the opaque colour of the area they belong to (`opaqueColor(fill)`), while the backdrop stays translucent. An earlier default drew fixed blue lines (`#4D88FF`), which falsely signaled an extra state on incident charts where colour is semantic.

package/USAGE.md

@@ -174,7 +174,67 @@ legend: {
 ```
 
 `outside-*` reserves margin space (the plot shrinks). `'separate'` draws **no** legend
-in the SVG — call `chart.legendItems()` (`{ name, color }[]`) and render your own HTML.
+in the SVG — call `chart.legendItems()` and render your own.
+
+### Drawing your own legend
+
+The built-in legend sits left or right inside the SVG and does nothing when clicked.
+Most applications want neither: a legend below the chart, in HTML, where a click hides
+a series. That is what `'separate'` is for.
+
+`legendItems()` returns what a swatch needs:
+
+```ts
+interface LegendItem {
+  name: string;
+  color: string;
+  line?: LineVariant;                     // 'dashed', 'dotted', … — undefined if the series has several lines
+  marker?: Exclude<PointStyleType, 'none'>; // only when the chart actually draws markers
+}
+```
+
+Draw the swatch through the same renderer the chart uses, so it cannot drift from the
+curve it names — a 22×10 line with the series' dashes and, if there is one, its marker:
+
+```ts
+import { drawMarker, SVGRenderer, type DrawCommand, type LegendItem } from 'ml-time-graph';
+
+function swatch(item: LegendItem): string {
+  const commands: DrawCommand[] = [
+    { type: 'line', x1: 1, y1: 5, x2: 21, y2: 5, stroke: item.color, strokeWidth: 2, dash: item.line },
+  ];
+  if (item.marker) {
+    drawMarker(commands, undefined, item.marker, 11, 5, 3, item.color, item.color, 1.5);
+  }
+  return new SVGRenderer({ width: 22, height: 10 }).render(commands).content;
+}
+```
+
+If you build the swatch in HTML or CSS instead of SVG, use **`resolveDash(variant, width)`**
+— it returns `{ strokeDasharray, strokeLinecap? }`, or `null` for a solid line, and it is the
+same function the renderer uses.
+
+> Use `resolveDash`, not `getLineStyle`, for anything that has to match a drawn line.
+> `dashed` and `dotted` predate the variant table and keep their historical patterns
+> (`"4,4"` and `"2,4"`, not scaled by stroke width) so that existing charts did not change
+> when the other variants arrived. `getLineStyle` is the table itself and answers `"6, 4"`
+> for `dashed` — correct as a table, wrong as a description of the curve. The difference is
+> nearly invisible and therefore worth knowing: a swatch dashed 6-on-4 beside a curve
+> dashed 4-on-4.
+
+**Why the swatch should not be a coloured block.** As long as series differ only by
+colour, a block is enough. The moment they differ by line style or marker — which is
+what you do when a chart is printed, or read by someone who cannot separate red from
+green — a block says nothing: on a black-and-white page every block is the same grey,
+and the legend is useless exactly where it is needed most, as part of a record.
+
+For the same reason `marker` is absent when the chart does not draw one. A series with
+`markers.threshold` hides its markers above that many samples; a symbol in the legend
+that is missing from the curve is a false statement, and on paper nobody can check.
+
+> `line` is undefined for a series drawn with **several** lines (`style.line` as an
+> array): there is no single answer, and the first one presented as the truth would be
+> a guess.
 
 ## Axes
 
@@ -470,7 +530,7 @@ renders the same JSON config to identical SVG.
 
 | Import | Contents |
 | :--- | :--- |
-| `ml-time-graph` | The rendering API — `mount`, `MLTimeGraph`, `SVGRenderer`, `attachTooltip`, and all option/data types. |
+| `ml-time-graph` | The rendering API — `mount`, `MLTimeGraph`, `SVGRenderer`, `attachTooltip`, the legend helpers `getLineStyle` / `drawMarker` / `getHatch`, 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. |

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { L as LegendOrientation, R as Renderer, M as Marker, a as LegendItem, b as LayoutResult, c as RenderOutput } from './layout-3caueyKS.js';
-export { T as Theme, g as getDefaultTheme, r as resetDefaultTheme, s as setDefaultTheme } from './layout-3caueyKS.js';
-import { L as LineVariant, A as AnySeries, T as Threshold, H as Highlight, G as Gap, a as GapsConfig, b as Annotation, c as AnnotationBandConfig, D as DrawCommand, d as TimeScale, e as LinearScale, S as SeriesStyle, F as FillSpec, f as TimeSeries, g as HatchVariant, h as ThresholdLabelPosition, P as PointStyleType, i as AnnotationBandItem, j as AggregatedPoint, k as AggregatedSeries, l as DataPoint } from './scale-CWAa8-uO.js';
-export { m as AggregationConfig, n as AggregationMode, o as DataPointRef, E as EnumMap, p as FillBound, q as FillDirectionType, r as FillRegion, s as FillSide, t as FillStyle, u as GapConfig, v as GapLabel, w as GapRegion, x as GapStyle, y as LineDashStyle, z as LineStyle, M as MarkerStyle, B as SensorType, C as SeriesOverlay, I as SeriesOverlayKind, J as SeriesType, K as ShadowStyle, N as ThresholdLabelConfig } from './scale-CWAa8-uO.js';
+import { L as LegendOrientation, R as Renderer, M as Marker, a as LegendItem, b as LayoutResult, c as RenderOutput } from './series_renderer-BxGvCHMY.js';
+export { T as Theme, d as drawMarker, g as getDefaultTheme, r as resetDefaultTheme, s as setDefaultTheme } from './series_renderer-BxGvCHMY.js';
+import { L as LineVariant, A as AnySeries, T as Threshold, H as Highlight, G as Gap, a as GapsConfig, b as Annotation, c as AnnotationBandConfig, D as DrawCommand, d as TimeScale, e as LinearScale, S as SeriesStyle, F as FillSpec, f as TimeSeries, g as HatchVariant, h as ThresholdLabelPosition, P as PointStyleType, i as AnnotationBandItem, j as AggregatedPoint, k as AggregatedSeries, l as DataPoint } from './scale-ByGpczxS.js';
+export { m as AggregationConfig, n as AggregationMode, o as DataPointRef, E as EnumMap, p as FillBound, q as FillDirectionType, r as FillRegion, s as FillSide, t as FillStyle, u as GapConfig, v as GapLabel, w as GapRegion, x as GapStyle, y as LineDashStyle, z as LineStyle, M as MarkerStyle, B as SVGLineStyle, C as SensorType, I as SeriesOverlay, J as SeriesOverlayKind, K as SeriesType, N as ShadowStyle, O as ThresholdLabelConfig, Q as getLineStyle, R as resolveDash } from './scale-ByGpczxS.js';
 
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
@@ -844,4 +844,4 @@ declare function parseSeries(obj: unknown): TimeSeries | DataPoint[];
 /** Parse aggregated series (AggregatedPoint[] — min/max/avg per slot) */
 declare function parseAggregated(obj: unknown): AggregatedSeries;
 
-export { AggregatedPoint, AggregatedSeries, Annotation, AnnotationBandBuilder, AnnotationBandConfig, AnnotationBandItem, AnnotationBandItemBuilder, AnnotationBuilder, AnySeries, type AxesConfig, type AxisLabelsStyle, type AxisStyle, DataPoint, type FillBetweenThresholdsInput, FillSpec, Gap, GapsConfig, GraphBuilder, type GridLineStyle, type GridStyle, HatchVariant, Highlight, HighlightBuilder, type LegendOptions, type LegendPosition, type LimitStatsPoint, MLTimeGraph, type MLTimeGraphOptions, type Margin, Marker, MarkerBuilder, type MktPoint, PointStyleType, SVGRenderer, SeriesStyle, type StatsAggregatedPoint, type StdDevPoint, Threshold, ThresholdBuilder, ThresholdLabelPosition, type TickConfig, TimeSeries, TimeSeriesBuilder, type TooltipOptions, type TooltipSample, type XAxisConfig, type YAxisConfig, attachTooltip, fillBetweenThresholds, mount, parseAggregated, parseDataPoint, parseSeries };
+export { AggregatedPoint, AggregatedSeries, Annotation, AnnotationBandBuilder, AnnotationBandConfig, AnnotationBandItem, AnnotationBandItemBuilder, AnnotationBuilder, AnySeries, type AxesConfig, type AxisLabelsStyle, type AxisStyle, DataPoint, DrawCommand, type FillBetweenThresholdsInput, FillSpec, Gap, GapsConfig, GraphBuilder, type GridLineStyle, type GridStyle, HatchVariant, Highlight, HighlightBuilder, LegendItem, type LegendOptions, LegendOrientation, type LegendPosition, type LimitStatsPoint, LineVariant, MLTimeGraph, type MLTimeGraphOptions, type Margin, Marker, MarkerBuilder, type MktPoint, PointStyleType, SVGRenderer, SeriesStyle, type StatsAggregatedPoint, type StdDevPoint, Threshold, ThresholdBuilder, ThresholdLabelPosition, type TickConfig, TimeSeries, TimeSeriesBuilder, type TooltipOptions, type TooltipSample, type XAxisConfig, type YAxisConfig, attachTooltip, fillBetweenThresholds, mount, parseAggregated, parseDataPoint, parseSeries };