wick-charts 0.5.0 → 0.6.0

package/README.md

@@ -19,6 +19,7 @@ npm install wick-charts
   - [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)
@@ -227,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)
@@ -644,8 +678,9 @@ concrete drawing tool ships yet, only the mechanism a trend line or similar woul
 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

@@ -76,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;
     /**
@@ -157,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. */

package/dist/index.js

@@ -3,6 +3,7 @@ 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';
@@ -302,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
@@ -464,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. */
@@ -527,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();
     }
@@ -674,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
@@ -702,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 {

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
@@ -249,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,
@@ -358,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/types.d.ts

@@ -173,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
@@ -199,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.5.0",
+  "version": "0.6.0",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",