wick-charts 0.4.0 → 0.5.0

package/README.md

@@ -17,6 +17,7 @@ npm install wick-charts
   - [Install](#install)
   - [Quick start](#quick-start)
   - [Candle data](#candle-data)
+  - [Line charts](#line-charts)
   - [Styling](#styling)
   - [Reading chart state](#reading-chart-state)
   - [Loading more history on demand](#loading-more-history-on-demand)
@@ -136,6 +137,39 @@ it — a dataset with no `volume` at all renders exactly as if the feature didn'
 array) is safe. It resets pan/zoom/hover state — call it for a genuinely new dataset, and use
 `setDataLoader()` (below) to extend the current one instead.
 
+### Line charts
+
+For a plain time series with no OHLC shape — an equity curve, a metric over time, anything
+that's just one number per point — `createLineChart` is the line-series equivalent of
+`createCandlestickChart` above. A line point is `{ time, value }`:
+
+```ts
+import { createLineChart } from 'wick-charts';
+
+const chart = createLineChart(canvas, {
+  style: { lineColor: '#2196f3', lineWidth: 1.5 }, // both shown here are the defaults
+});
+
+chart.setData([
+  { time: '2024-01-01T00:00:00Z', value: 100 },
+  { time: '2024-01-02T00:00:00Z', value: 103.4 },
+  { time: '2024-01-03T00:00:00Z', value: 101.8 },
+  // ...
+]);
+
+chart.render();
+```
+
+Everything else — pan/zoom/hover, `setDataLoader`, `addPlugin`, `addPane`, `background`/
+`font`/`axis`/`crosshair`/`legend` styling — works exactly as it does for a candlestick chart,
+since none of it is specific to what's actually plotted (see "Series types" under
+Architecture). `value` accepts `NaN` (or any non-finite number) as an explicit gap: the line
+breaks there and resumes at the next real value, rather than plotting a bogus point or
+throwing — useful for a series with missing data at some points without pre-filtering it
+yourself. The hover legend shows `Value <number>` (or `Value —` for a hovered gap) in place of
+candlestick's OHLC breakdown; `new WickChart(canvas, { type: 'line' })` also works, the same
+untyped escape hatch `type: 'candlestick'` has, if you'd rather not import the factory.
+
 ### Styling
 
 Every visual aspect of the chart is an option — nothing is a fixed constant you can't reach.
@@ -455,31 +489,35 @@ for *this* series (a line series wouldn't have a body width or volume bars to co
 
 ### Series types
 
-Candlesticks are the only chart type today, but nothing above `src/series/` knows that.
-`WickChart` and `ChartRenderer` are generic over a point shape (`SeriesPoint` — just a
-`time`) and delegate every type-specific decision — how to compute the value-axis range,
-how to draw the visible points, what a hover legend says — to a
+Candlestick and line are the two chart types today, and nothing above `src/series/` treats
+either specially. `WickChart` and `ChartRenderer` are generic over a point shape
+(`SeriesPoint` — just a `time`) and delegate every type-specific decision — how to compute
+the value-axis range, how to draw the visible points, what a hover legend says — to a
 `SeriesDefinition` (see `src/series/types.ts`) resolved at construction time from
 `options.type` via a small registry (`src/series/registry.ts`). `src/series/candlestick.ts`
-is the reference implementation: it registers itself as `'candlestick'` on import, which is
-why importing `wick-charts` at all is enough to make that type available without the caller
-registering anything.
-
-Adding a second chart type (line, area, bar, ...) means writing one new file that
-implements `SeriesDefinition<TPoint, TStyle>` and calling `registerSeries` on it — `Viewport`,
-event handling, data loading, and WASM scale dispatch are all untouched, and existing
-`type: 'candlestick'` charts keep working exactly as before. This is the extension point the
-`type` option and `style` option are built around: `style` is whatever shape the chosen
-series's `defaultStyle` declares (candlestick's is `{ upColor, downColor }`), merged over
-that default rather than hardcoded into the chart itself.
+and `src/series/line.ts` both register themselves (as `'candlestick'`/`'line'`) on import,
+which is why importing `wick-charts` at all is enough to make either type available without
+the caller registering anything.
+
+Adding a chart type (area, bar, ...) means writing one new file that implements
+`SeriesDefinition<TPoint, TStyle>` and calling `registerSeries` on it — `Viewport`, event
+handling, data loading, and WASM scale dispatch are all untouched, and every existing chart
+of another type keeps working exactly as before; `src/series/line.ts` is a second, smaller
+worked example of this alongside candlestick's own. This is the extension point the `type`
+option and `style` option are built around: `style` is whatever shape the chosen series's
+`defaultStyle` declares (candlestick's is `{ upColor, downColor, ... }`, line's is `{
+lineColor, lineWidth }`), merged over that default rather than hardcoded into the chart
+itself.
 
 `options.type` is a plain string the registry resolves at runtime, so `new WickChart(canvas,
 { type: 'candlestick', style: {...} })` type-checks even if `style` has nothing to do with
 `CandlestickStyle` — nothing ties a runtime string to a specific `TPoint`/`TStyle` pair at the
-type level. `createCandlestickChart()` (in `src/index.ts`) is the fix for the one built-in
-type: a thin wrapper that pins both generics so its `style` is fully checked. A new series
-should export an equivalent `create<Name>Chart` next to it rather than widening
-`WickChartOptions` itself, so each series's style shape stays independent of every other's.
+type level. `createCandlestickChart()`/`createLineChart()` (both in `src/index.ts`) are the
+fix for the two built-in types: a thin wrapper per series that pins both generics so its
+`style` is fully checked. A new series should export an equivalent `create<Name>Chart` next
+to it rather than widening `WickChartOptions` itself, so each series's style shape stays
+independent of every other's — line's factory is the second proof this pattern holds up, not
+just a one-off written for candlestick.
 
 ### Plugins (markers, annotations, drawing tools)
 
@@ -598,7 +636,8 @@ hover state — and on-demand history loading via `setDataLoader`. Per-candle vo
 the bottom fifth of the chart when a candle has `volume`, and are entirely omitted (nothing
 drawn, nothing reserved) for data that doesn't.
 Coordinate scaling runs on WASM once a frame's point count crosses the threshold, JS below
-it. Candlestick is the only registered series type so far; the plugin extension point (draw
+it. Candlestick and line are the two registered series types so far (`createCandlestickChart`/
+`createLineChart`); the plugin extension point (draw
 overlays plus, now, claimable pointer gestures for interactive tools — see "Plugins" above)
 has no built-in users (see "Indicators" above for why) beyond `demo/index.html`'s example. No
 concrete drawing tool ships yet, only the mechanism a trend line or similar would be built

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import type { DataLoader } from './dataSource.js';
 import type { ChartPlugin } from './plugins/types.js';
 import type { CandlestickStyle } from './series/candlestick.js';
-import type { Candle, PaneOptions, WickChartOptions, SeriesPoint, ValueRange } from './types.js';
-export type { BusinessDay, Candle, PaneOptions, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange, } from './types.js';
+import type { LineStyle } from './series/line.js';
+import type { Candle, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange } from './types.js';
+export type { BusinessDay, Candle, LinePoint, PaneOptions, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange, } from './types.js';
 export type { DataLoader, DataRequest } from './dataSource.js';
 export type { ChartPlugin, ChartPointerEvent, PluginRenderApi } from './plugins/types.js';
 export { distanceToSegment, hitTestPoint, hitTestSegment } from './hitTest.js';
@@ -11,7 +12,9 @@ export { mergeSeriesPoints } from './mergeSeries.js';
 export { registerSeries, getSeries } from './series/registry.js';
 export type { SeriesDefinition, SeriesDrawContext } from './series/types.js';
 export type { CandlestickStyle } from './series/candlestick.js';
+export type { LineStyle } from './series/line.js';
 export { candlestickSeries } from './series/candlestick.js';
+export { lineSeries } from './series/line.js';
 export { LinearScale } from './scale.js';
 export { toUnixSeconds } from './time.js';
 export { Viewport } from './viewport.js';
@@ -268,3 +271,13 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
 export declare function createCandlestickChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style'> & {
     style?: Partial<CandlestickStyle>;
 }): WickChart<Candle>;
+/**
+ * The second series type's equivalent of `createCandlestickChart` above —
+ * pins `TPoint` (`LinePoint`) and `TStyle` (`LineStyle`) so `style` is
+ * fully checked here the same way, rather than accepted as the untyped
+ * `Record<string, unknown>` `WickChartOptions.style` allows for `new
+ * WickChart(canvas, { type: 'line', style })`.
+ */
+export declare function createLineChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style'> & {
+    style?: Partial<LineStyle>;
+}): WickChart<LinePoint>;

package/dist/index.js

@@ -9,13 +9,14 @@ import { importRealWasm } from './wasmImporter.js';
 export { distanceToSegment, hitTestPoint, hitTestSegment } from './hitTest.js';
 export { mergeSeriesPoints } from './mergeSeries.js';
 export { registerSeries, getSeries } from './series/registry.js';
-// Also registers the 'candlestick' type as a module-load side effect — see
-// src/series/candlestick.ts and src/series/registry.ts. A new series type
-// gets the same treatment: implement SeriesDefinition, export it here (or
-// have the consuming app import it directly before constructing a chart of
-// that type), and `type: '<its key>'` becomes usable with no other change
-// to this file.
+// Also registers 'candlestick'/'line' as a module-load side effect — see
+// src/series/candlestick.ts, src/series/line.ts, and src/series/registry.ts.
+// A new series type gets the same treatment: implement SeriesDefinition,
+// export it here (or have the consuming app import it directly before
+// constructing a chart of that type), and `type: '<its key>'` becomes
+// usable with no other change to this file.
 export { candlestickSeries } from './series/candlestick.js';
+export { lineSeries } from './series/line.js';
 export { LinearScale } from './scale.js';
 export { toUnixSeconds } from './time.js';
 export { Viewport } from './viewport.js';
@@ -781,3 +782,13 @@ export class WickChart {
 export function createCandlestickChart(canvas, options) {
     return new WickChart(canvas, { ...options, type: 'candlestick' });
 }
+/**
+ * The second series type's equivalent of `createCandlestickChart` above —
+ * pins `TPoint` (`LinePoint`) and `TStyle` (`LineStyle`) so `style` is
+ * fully checked here the same way, rather than accepted as the untyped
+ * `Record<string, unknown>` `WickChartOptions.style` allows for `new
+ * WickChart(canvas, { type: 'line', style })`.
+ */
+export function createLineChart(canvas, options) {
+    return new WickChart(canvas, { ...options, type: 'line' });
+}

package/dist/renderer.js

@@ -142,7 +142,21 @@ export class ChartRenderer {
             // Exact inverse of xForIndex above — solving
             // `x = (index - viewport.startIndex) * slotWidth + slotWidth / 2` for `index`.
             const indexForX = (x) => viewport.startIndex + (x - slotWidth / 2) / slotWidth;
-            seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight }, style);
+            // save/restore isolates whatever canvas state a series's draw()
+            // touches (lineWidth, line dash, ...) from the axis/crosshair/plugin
+            // drawing that follows — the same isolation each plugin already gets
+            // around its own draw() call below. Without this, a property no
+            // series happened to set before (lineSeries.draw() is the first
+            // built-in one to set ctx.lineWidth) would silently leak into every
+            // subsequent stroke() this frame, including axis boundary lines,
+            // grid lines, and the crosshair.
+            ctx.save();
+            try {
+                seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight }, style);
+            }
+            finally {
+                ctx.restore();
+            }
             const priceStep = this.currentPriceStep(valueMin, valueMax);
             this.renderPriceAxis(valueMin, valueMax, priceStep, yScale, chartWidth, chartHeight, mainRect.top);
             for (const { rect, min, max, scale } of paneScales) {

package/dist/series/line.d.ts

@@ -0,0 +1,14 @@
+import type { LinePoint } from '../types.js';
+import type { SeriesDefinition } from './types.js';
+/** The second built-in series type — a plain single-value line, the
+ * simplest possible `SeriesDefinition` beyond candlestick's OHLC. Exists as
+ * much to exercise the registry with a genuinely different `TPoint`/`TStyle`
+ * pair as to be useful on its own; see `src/series/candlestick.ts` for the
+ * reference implementation this mirrors. */
+export interface LineStyle {
+    /** Stroke color. Defaults to `'#2196f3'`. */
+    lineColor: string;
+    /** Stroke width, in px. Defaults to 1.5. */
+    lineWidth: number;
+}
+export declare const lineSeries: SeriesDefinition<LinePoint, LineStyle>;

package/dist/series/line.js

@@ -0,0 +1,65 @@
+import { fitRange } from '../priceRange.js';
+import { registerSeries } from './registry.js';
+const DEFAULT_STYLE = {
+    lineColor: '#2196f3',
+    lineWidth: 1.5,
+};
+/** Falls back to a fixed `[0, 1]` range when every visible point is a gap
+ * (`NaN`/non-finite `value`) — `Math.min()`/`Math.max()` over an empty
+ * array are `Infinity`/`-Infinity`, which would otherwise feed `fitRange`
+ * a `NaN` midpoint. Candlestick never needs this: `Candle`'s OHLC fields
+ * aren't optional or gap-tolerant the way a line point's `value` is. */
+function getValueRange(visible, scaleFactor) {
+    const values = visible.map((p) => p.value).filter((v) => Number.isFinite(v));
+    if (values.length === 0)
+        return { min: 0, max: 1 };
+    return fitRange(Math.min(...values), Math.max(...values), scaleFactor);
+}
+function draw(context, style) {
+    const { ctx, visible, startIndex, xForIndex, yScale } = context;
+    if (visible.length === 0)
+        return;
+    // Batched through mapMany (one call per array) rather than once per
+    // point in the loop below — same reasoning as candlestick's draw(): it's
+    // what lets the WASM path pay the JS<->WASM boundary cost once per frame.
+    // NaN values map to NaN here, harmlessly — skipped below rather than
+    // filtered out first, so `ys[i]` still lines up with `visible[i]`.
+    const ys = yScale.mapMany(visible.map((p) => p.value));
+    ctx.strokeStyle = style.lineColor;
+    ctx.lineWidth = style.lineWidth;
+    ctx.beginPath();
+    // `drawing` tracks whether the path is mid-segment — a non-finite value
+    // (a gap in the data) breaks it, and the line resumes fresh at the next
+    // real value rather than jumping straight across the gap.
+    let drawing = false;
+    visible.forEach((point, i) => {
+        if (!Number.isFinite(point.value)) {
+            drawing = false;
+            return;
+        }
+        const x = xForIndex(startIndex + i);
+        const y = ys[i];
+        if (drawing) {
+            ctx.lineTo(x, y);
+        }
+        else {
+            ctx.moveTo(x, y);
+            drawing = true;
+        }
+    });
+    ctx.stroke();
+}
+function formatLegend(point) {
+    return [`Value ${Number.isFinite(point.value) ? point.value.toLocaleString('en-US') : '—'}`];
+}
+export const lineSeries = {
+    type: 'line',
+    defaultStyle: DEFAULT_STYLE,
+    getValueRange,
+    draw,
+    formatLegend,
+};
+// Registered as a module-level side effect, same as candlestickSeries — see
+// src/series/candlestick.ts for why. src/index.ts imports this file so
+// 'line' is available the moment the package itself is imported.
+registerSeries(lineSeries);

package/dist/types.d.ts

@@ -57,6 +57,18 @@ export interface Candle extends SeriesPoint {
     close: number;
     volume?: number;
 }
+/**
+ * A single value plotted against time — the point shape for the built-in
+ * `'line'` series (see `src/series/line.ts`), and the simplest possible
+ * instance of `SeriesPoint` beyond `Candle`: a plain time series with
+ * nothing OHLC-specific about it. `value` is `NaN`-tolerant: a `NaN`
+ * (or non-finite) value is treated as a gap — the line breaks there and
+ * resumes at the next real value, rather than plotting a bogus point or
+ * throwing.
+ */
+export interface LinePoint extends SeriesPoint {
+    value: number;
+}
 /** Text styling shared by every label the chart draws — axis ticks,
  * crosshair axis labels, and the hover legend. `axisSize`/`legendSize` are
  * separate since the legend has historically been drawn one px larger to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wick-charts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",