wick-charts 0.4.0 → 0.6.0

package/README.md

@@ -17,7 +17,9 @@ npm install wick-charts
   - [Install](#install)
   - [Quick start](#quick-start)
   - [Candle data](#candle-data)
+  - [Line charts](#line-charts)
   - [Styling](#styling)
+  - [Inverting the value axis](#inverting-the-value-axis)
   - [Reading chart state](#reading-chart-state)
   - [Loading more history on demand](#loading-more-history-on-demand)
   - [Extending: plugins](#extending-plugins)
@@ -136,6 +138,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.
@@ -193,6 +228,39 @@ type-checks `style` against
 `CandlestickStyle`; the more general `new WickChart(canvas, { type: 'candlestick', style })`
 also works but doesn't — see "Series types" below for why, if you're curious.
 
+### Inverting the value axis
+
+`invertValueAxis` mirrors the value axis top-to-bottom — every pane's higher values render
+lower on screen instead of higher, useful for a "what if this series had moved the opposite
+way" view:
+
+```ts
+const chart = createCandlestickChart(canvas, { invertValueAxis: true });
+```
+
+Unlike the style options above, it's meant to be flipped live rather than fixed at
+construction — `setInvertValueAxis(boolean)`/`isValueAxisInverted()` let a UI toggle it on an
+existing chart without losing the current pan/zoom position or manual value-range override,
+the same way `setPluginVisible` toggles a plugin without losing its state:
+
+```ts
+toggleButton.addEventListener('click', () => {
+  chart.setInvertValueAxis(!chart.isValueAxisInverted());
+});
+```
+
+Only where each value renders is mirrored — the underlying data isn't. A candle's open/close
+relationship (and therefore its up/down color) still reflects the real values, `formatLegend`
+still shows the real OHLC numbers, and dragging the price axis or panning vertically still
+feels like "grab and slide" in the same screen direction as before; only the sign of what that
+drag does to the value range flips internally to keep it feeling that way. Applies to every
+pane in the stack (see "Multi-pane indicators" below) consistently, not just the main one.
+
+One known exception: candlestick's volume bars aren't mapped through the value-axis scale at
+all (they're drawn in a fixed-height strip anchored to the bottom of the pane, independent of
+price — see "Series types" under Architecture), so they stay bottom-anchored regardless of
+`invertValueAxis` rather than flipping to the top with everything else.
+
 ### Reading chart state
 
 Useful for building UI around the canvas (a legend, a toolbar, a "jump to latest" button)
@@ -455,31 +523,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,15 +670,17 @@ 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
 on. `addPane`/`removePane` let a plugin-drawn indicator (RSI, MACD, ...) reserve its own
 horizontal strip with an independent value axis — see "Multi-pane indicators" above; volume
 still shares the candlestick pane rather than getting its own, since it draws through the
-series itself, not a pane-targeted plugin. See [CHANGELOG.md](./CHANGELOG.md) for what shipped
-in each release.
+series itself, not a pane-targeted plugin. `invertValueAxis`/`setInvertValueAxis` mirror the
+whole stack's value axis top-to-bottom without touching the underlying data — see "Inverting
+the value axis" above. See [CHANGELOG.md](./CHANGELOG.md) for what shipped in each release.
 
 ## License
 

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';
@@ -73,6 +76,11 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
      * every threshold crossing until `setData` resets it (a fresh dataset
      * may come from a different source that does have more). */
     private exhausted;
+    /** Mirrors `this.renderer`'s own copy (set at construction, kept in sync
+     * by `setInvertValueAxis`) — needed here too since pointer-event value
+     * conversion and price-axis drag direction happen outside `render()`,
+     * where only `WickChart` (not `ChartRenderer`) is involved. */
+    private invertValueAxis;
     constructor(canvas: HTMLCanvasElement, options?: WickChartOptions);
     setData(points: TPoint[]): this;
     /**
@@ -154,6 +162,17 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
     /** The point currently under the cursor (crosshair/legend target), or
      * `null` when nothing is hovered. */
     getHoveredPoint(): TPoint | null;
+    /**
+     * Mirrors the value axis top-to-bottom (or restores it) and re-renders —
+     * see `WickChartOptions.invertValueAxis` for what this actually changes.
+     * A live toggle, unlike most other style options: pan/zoom/valueRangeOverride
+     * state is untouched, so a "flip" button can call this on an existing
+     * chart without losing the user's current view, the same way
+     * `setPluginVisible` toggles a plugin without losing its state.
+     */
+    setInvertValueAxis(inverted: boolean): this;
+    /** Whether the value axis is currently mirrored — see `setInvertValueAxis`. */
+    isValueAxisInverted(): boolean;
     /** Removes all attached listeners. Call on unmount — the mouseup
      * listener is on `window` (so drags don't get stuck if the cursor
      * leaves the canvas mid-drag) and won't be garbage-collected on its own. */
@@ -268,3 +287,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

@@ -3,19 +3,21 @@ import { computePaneLayout } from './paneLayout.js';
 import { ChartRenderer } from './renderer.js';
 import { getSeries } from './series/registry.js';
 import { toUnixSeconds } from './time.js';
+import { pixelToValue, valueToPixel } from './valueAxis.js';
 import { Viewport } from './viewport.js';
 import { loadWasm } from './wasm.js';
 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';
@@ -301,6 +303,7 @@ export class WickChart {
         };
         this.seriesDefinition = getSeries(options?.type ?? 'candlestick');
         this.renderer = new ChartRenderer(canvas, this.seriesDefinition, options);
+        this.invertValueAxis = options?.invertValueAxis ?? false;
         this.viewport = new Viewport(0);
         // Without this, a touch drag on the canvas also scrolls/zooms the page
         // underneath it — the browser's native touch gestures and this class's
@@ -463,6 +466,24 @@ export class WickChart {
     getHoveredPoint() {
         return this.hoverIndex === null ? null : (this.sorted[this.hoverIndex] ?? null);
     }
+    /**
+     * Mirrors the value axis top-to-bottom (or restores it) and re-renders —
+     * see `WickChartOptions.invertValueAxis` for what this actually changes.
+     * A live toggle, unlike most other style options: pan/zoom/valueRangeOverride
+     * state is untouched, so a "flip" button can call this on an existing
+     * chart without losing the user's current view, the same way
+     * `setPluginVisible` toggles a plugin without losing its state.
+     */
+    setInvertValueAxis(inverted) {
+        this.invertValueAxis = inverted;
+        this.renderer.setInvertValueAxis(inverted);
+        this.scheduleRender();
+        return this;
+    }
+    /** Whether the value axis is currently mirrored — see `setInvertValueAxis`. */
+    isValueAxisInverted() {
+        return this.invertValueAxis;
+    }
     /** Removes all attached listeners. Call on unmount — the mouseup
      * listener is on `window` (so drags don't get stuck if the cursor
      * leaves the canvas mid-drag) and won't be garbage-collected on its own. */
@@ -526,7 +547,13 @@ export class WickChart {
             // Dragging down moves the visible value window down (content
             // follows the cursor), matching the horizontal drag's "grab and
             // slide" feel — see the pan call above for the mirrored X case.
-            this.viewport.panValueRange(deltaYDevice * valuePerPixel);
+            // invertValueAxis flips which value-space direction "down the
+            // screen" corresponds to (see src/valueAxis.ts), so the sign here
+            // has to flip too or an inverted chart would pan backwards relative
+            // to the drag — negated, not re-derived, since the *magnitude* is
+            // identical either way.
+            const directionSign = this.invertValueAxis ? -1 : 1;
+            this.viewport.panValueRange(deltaYDevice * valuePerPixel * directionSign);
         }
         this.scheduleRender();
     }
@@ -673,7 +700,7 @@ export class WickChart {
         const chartHeight = this.mainPaneHeight();
         if (!range || chartHeight <= 0)
             return null;
-        return range.min + (1 - y / chartHeight) * (range.max - range.min);
+        return pixelToValue(y, range.min, range.max, chartHeight, this.invertValueAxis);
     }
     /** x pixel -> global (possibly fractional) index — the exact inverse of
      * the renderer's own `xForIndex`, so a pointer event lines up with
@@ -701,7 +728,7 @@ export class WickChart {
         const chartHeight = this.mainPaneHeight();
         if (!range || chartHeight <= 0)
             return null;
-        return chartHeight * (1 - (value - range.min) / (range.max - range.min));
+        return valueToPixel(value, range.min, range.max, chartHeight, this.invertValueAxis);
     }
     pointerEventAt(x, y) {
         return {
@@ -781,3 +808,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.d.ts

@@ -48,7 +48,14 @@ export declare class ChartRenderer<TPoint extends SeriesPoint> {
     private axis;
     private crosshair;
     private legend;
+    /** Unlike the style groups above, mutable after construction — see
+     * `setInvertValueAxis`. A live toggle, not a one-time style choice, is
+     * the whole point of this option (a "what if this series moved the
+     * opposite way" view a user flips on and off), so it doesn't get the
+     * "resolved once in the constructor" treatment those get. */
+    private invertValueAxis;
     constructor(canvas: HTMLCanvasElement, seriesDefinition: SeriesDefinition<TPoint, unknown>, options?: WickChartOptions);
+    setInvertValueAxis(inverted: boolean): void;
     /** Pixel width of the point-plotting area — excludes the price-axis
      * strip on the right. Exposed so `WickChart` can convert cursor pixel
      * positions to point indices / values for hit-testing and dragging. */

package/dist/renderer.js

@@ -2,6 +2,7 @@ import { formatAxisLabel, formatHoverTime, pickTickIndices } from './axis.js';
 import { createScale } from './hybridScale.js';
 import { computePaneLayout } from './paneLayout.js';
 import { formatPrice, niceTicks } from './priceAxis.js';
+import { pixelToValue, valueAxisPixelRange } from './valueAxis.js';
 const DEFAULT_BACKGROUND = 'transparent';
 const DEFAULT_FONT = {
     family: 'sans-serif',
@@ -61,6 +62,10 @@ export class ChartRenderer {
         this.axis = { ...DEFAULT_AXIS, ...options.axis };
         this.crosshair = { ...DEFAULT_CROSSHAIR, ...options.crosshair };
         this.legend = { ...DEFAULT_LEGEND, ...options.legend };
+        this.invertValueAxis = options.invertValueAxis ?? false;
+    }
+    setInvertValueAxis(inverted) {
+        this.invertValueAxis = inverted;
     }
     /** Pixel width of the point-plotting area — excludes the price-axis
      * strip on the right. Exposed so `WickChart` can convert cursor pixel
@@ -112,16 +117,20 @@ export class ChartRenderer {
         // JS below a few hundred points, WASM above — see hybridScale.ts.
         // Whichever it picks, `dispose()` must run once we're done reading
         // from it (a no-op on the JS path, a real WASM memory free otherwise).
-        const { scale: yScale, dispose: disposeYScale } = createScale(valueMin, valueMax, chartHeight, 0, visible.length);
+        // valueAxisPixelRange picks which pixel end is the domain minimum —
+        // the one thing invertValueAxis actually changes about this call.
+        const { scale: yScale, dispose: disposeYScale } = createScale(valueMin, valueMax, ...valueAxisPixelRange(chartHeight, this.invertValueAxis), visible.length);
         // Every indicator pane gets the exact same treatment as the main pane
         // — its own value domain (from `PaneOptions.getValueRange`) and its
         // own JS/WASM scale over its own pixel height — kept alive for the
         // whole frame alongside `yScale`, since plugins targeting a pane draw
-        // only after every pane's axis has already been rendered.
+        // only after every pane's axis has already been rendered. Inverted the
+        // same way as the main pane so a chart's invertValueAxis option
+        // mirrors its whole stack consistently, not just the price pane.
         const paneScales = paneRects.map((rect, i) => {
             const pane = panes[i];
             const { min, max } = pane.getValueRange();
-            const { scale, dispose } = createScale(min, max, rect.height, 0, visible.length);
+            const { scale, dispose } = createScale(min, max, ...valueAxisPixelRange(rect.height, this.invertValueAxis), visible.length);
             return { pane, rect, min, max, scale, dispose };
         });
         // Flipped in `finally`, right before every scale above frees its WASM
@@ -142,7 +151,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) {
@@ -235,9 +258,10 @@ export class ChartRenderer {
             },
             indexForX,
             // Exact inverse of the mapping above: subtract the pane's top offset
-            // before inverting the same [valueMin, valueMax] -> [rect.height, 0]
-            // mapping createScale set up for it.
-            valueForY: (y) => valueMin + (1 - (y - rect.top) / rect.height) * (valueMax - valueMin),
+            // before inverting the same value<->pixel mapping createScale set up
+            // for it (see src/valueAxis.ts — same invertValueAxis flag, so this
+            // stays consistent with whichever direction the pane actually drew in).
+            valueForY: (y) => pixelToValue(y - rect.top, valueMin, valueMax, rect.height, this.invertValueAxis),
             visibleStartIndex,
             visibleEndIndex,
             allPoints,
@@ -344,8 +368,9 @@ export class ChartRenderer {
         ctx.restore();
         if (priceLineVisible) {
             // Exact inverse of the value->y mapping createScale set up for this
-            // frame — same formula as PluginRenderApi.valueForY.
-            const value = valueMin + (1 - hoverY / chartHeight) * (valueMax - valueMin);
+            // frame — same helper (and same invertValueAxis flag) as
+            // PluginRenderApi.valueForY, see src/valueAxis.ts.
+            const value = pixelToValue(hoverY, valueMin, valueMax, chartHeight, this.invertValueAxis);
             this.renderPriceLabelChip(formatPrice(value, priceStep), hoverY, chartWidth);
         }
         this.renderTimeLabelChip(formatHoverTime(timeSeconds), x, chartHeight, canvas.width);

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
@@ -161,9 +173,9 @@ export interface WickChartOptions {
     /**
      * Which registered series type to render this chart as (see
      * `registerSeries` in `src/series/registry.ts`). Defaults to
-     * `'candlestick'`, the only type built into the library today — adding a
-     * new one is a matter of implementing `SeriesDefinition` and registering
-     * it, without changing `WickChart` or `ChartRenderer` at all.
+     * `'candlestick'`; `'line'` is the other type built into the library —
+     * adding a new one is a matter of implementing `SeriesDefinition` and
+     * registering it, without changing `WickChart` or `ChartRenderer` at all.
      */
     type?: string;
     /** Background color of the canvas. Defaults to transparent. Chart-wide
@@ -187,4 +199,15 @@ export interface WickChartOptions {
     crosshair?: ChartCrosshairOptions;
     /** Hover legend coloring. Merged over the built-in defaults field by field. */
     legend?: ChartLegendOptions;
+    /**
+     * Mirrors the value axis top-to-bottom — every pane's higher values
+     * render lower on screen instead of higher, with no change to the
+     * underlying data (a candle's open/close relationship, and therefore
+     * its up/down color, is unaffected). Defaults to `false`. Useful for a
+     * "what if this series had moved the opposite way" view. Can also be
+     * toggled after construction via `WickChart.setInvertValueAxis` without
+     * losing pan/zoom state — see `src/valueAxis.ts` for the mapping this
+     * flips.
+     */
+    invertValueAxis?: boolean;
 }

package/dist/valueAxis.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure pixel<->value mapping helpers for a chart's value axis, factored out
+ * so `WickChartOptions.invertValueAxis` (see `src/index.ts`) has exactly
+ * one place to change the y-direction convention instead of several
+ * independently re-derived copies of the same formula. Before this file
+ * existed, `ChartRenderer`'s hover-crosshair value readout, its per-pane
+ * `PluginRenderApi.valueForY`, and `WickChart`'s own pointer-event
+ * `value`/`yForValue` each inlined the same "pixel -> value" arithmetic
+ * separately — harmless while there was only ever one direction, but
+ * exactly the kind of duplication that turns "add an invert option" into
+ * "find and fix four copies of a formula, hope none were missed."
+ *
+ * The forward, per-point-in-a-frame hot path stays on `Scale`
+ * (`src/hybridScale.ts`, JS or WASM) for its own reasons — batched
+ * `mapMany`, no per-point allocation. `valueAxisPixelRange` only decides
+ * which pixel end a `Scale` should treat as the domain minimum, so
+ * inverting is a one-line change to how a `Scale` gets constructed rather
+ * than a second rendering path. `valueToPixel`/`pixelToValue` below are for
+ * the comparatively rare user-gesture paths (hover crosshair, pointer
+ * events, price-axis dragging) where a `Scale` instance either doesn't
+ * exist yet (these happen between frames) or isn't worth constructing for
+ * a single one-off conversion.
+ */
+/**
+ * The `[rangeMin, rangeMax]` pair to construct a value-axis `Scale` with:
+ * `createScale(domainMin, domainMax, ...valueAxisPixelRange(pixelSpan, inverted))`.
+ * Not inverted (the default for every chart): the domain maximum renders
+ * at pixel 0 (the top of the pane) and the minimum at `pixelSpan` (the
+ * bottom). Inverted: the same two pixels, swapped — every value renders
+ * mirrored top-to-bottom, with no change to the underlying data.
+ */
+export declare function valueAxisPixelRange(pixelSpan: number, inverted: boolean): [number, number];
+/**
+ * value -> pixel, the exact forward direction `valueAxisPixelRange` sets a
+ * `Scale` up for. `pixelSpan` is the pane's own height (or a candidate
+ * one — this has no dependency on `Scale` or a live frame).
+ */
+export declare function valueToPixel(value: number, valueMin: number, valueMax: number, pixelSpan: number, inverted: boolean): number;
+/**
+ * pixel -> value, the exact inverse of `valueToPixel` above —
+ * `valueToPixel(pixelToValue(pixel, ...), ...) === pixel` for any `pixel`
+ * in `[0, pixelSpan]`.
+ */
+export declare function pixelToValue(pixel: number, valueMin: number, valueMax: number, pixelSpan: number, inverted: boolean): number;

package/dist/valueAxis.js

@@ -0,0 +1,52 @@
+/**
+ * Pure pixel<->value mapping helpers for a chart's value axis, factored out
+ * so `WickChartOptions.invertValueAxis` (see `src/index.ts`) has exactly
+ * one place to change the y-direction convention instead of several
+ * independently re-derived copies of the same formula. Before this file
+ * existed, `ChartRenderer`'s hover-crosshair value readout, its per-pane
+ * `PluginRenderApi.valueForY`, and `WickChart`'s own pointer-event
+ * `value`/`yForValue` each inlined the same "pixel -> value" arithmetic
+ * separately — harmless while there was only ever one direction, but
+ * exactly the kind of duplication that turns "add an invert option" into
+ * "find and fix four copies of a formula, hope none were missed."
+ *
+ * The forward, per-point-in-a-frame hot path stays on `Scale`
+ * (`src/hybridScale.ts`, JS or WASM) for its own reasons — batched
+ * `mapMany`, no per-point allocation. `valueAxisPixelRange` only decides
+ * which pixel end a `Scale` should treat as the domain minimum, so
+ * inverting is a one-line change to how a `Scale` gets constructed rather
+ * than a second rendering path. `valueToPixel`/`pixelToValue` below are for
+ * the comparatively rare user-gesture paths (hover crosshair, pointer
+ * events, price-axis dragging) where a `Scale` instance either doesn't
+ * exist yet (these happen between frames) or isn't worth constructing for
+ * a single one-off conversion.
+ */
+/**
+ * The `[rangeMin, rangeMax]` pair to construct a value-axis `Scale` with:
+ * `createScale(domainMin, domainMax, ...valueAxisPixelRange(pixelSpan, inverted))`.
+ * Not inverted (the default for every chart): the domain maximum renders
+ * at pixel 0 (the top of the pane) and the minimum at `pixelSpan` (the
+ * bottom). Inverted: the same two pixels, swapped — every value renders
+ * mirrored top-to-bottom, with no change to the underlying data.
+ */
+export function valueAxisPixelRange(pixelSpan, inverted) {
+    return inverted ? [0, pixelSpan] : [pixelSpan, 0];
+}
+/**
+ * value -> pixel, the exact forward direction `valueAxisPixelRange` sets a
+ * `Scale` up for. `pixelSpan` is the pane's own height (or a candidate
+ * one — this has no dependency on `Scale` or a live frame).
+ */
+export function valueToPixel(value, valueMin, valueMax, pixelSpan, inverted) {
+    const t = (value - valueMin) / (valueMax - valueMin);
+    return inverted ? t * pixelSpan : (1 - t) * pixelSpan;
+}
+/**
+ * pixel -> value, the exact inverse of `valueToPixel` above —
+ * `valueToPixel(pixelToValue(pixel, ...), ...) === pixel` for any `pixel`
+ * in `[0, pixelSpan]`.
+ */
+export function pixelToValue(pixel, valueMin, valueMax, pixelSpan, inverted) {
+    const t = inverted ? pixel / pixelSpan : 1 - pixel / pixelSpan;
+    return valueMin + t * (valueMax - valueMin);
+}

package/package.json

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