wick-charts 0.5.0 → 0.7.0

package/README.md

@@ -19,7 +19,9 @@ 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)
+  - [Setting the visible range](#setting-the-visible-range)
   - [Loading more history on demand](#loading-more-history-on-demand)
   - [Extending: plugins](#extending-plugins)
   - [Multi-pane indicators](#multi-pane-indicators)
@@ -227,6 +229,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)
@@ -235,10 +270,47 @@ without reaching into the chart's internals:
 ```ts
 chart.getPointCount();        // total candles loaded (not just visible)
 chart.getVisibleRange();      // { startIndex, endIndex, visibleCount }
+chart.getVisibleTimeRange();  // { from, to } in unix seconds, or null with no data
 chart.getValueRangeOverride(); // { min, max } once the user has dragged the price axis, else null
 chart.getHoveredPoint();      // the candle under the cursor/finger, or null
 ```
 
+### Setting the visible range
+
+The write side of `getVisibleRange`/`getVisibleTimeRange` — jump the pan/zoom window
+programmatically instead of only ever through a drag/scroll gesture:
+
+```ts
+chart.setVisibleRange({ startIndex: 50, endIndex: 100 }); // index-based, like getVisibleRange()
+chart.setVisibleTimeRange({ from: '2024-02-01T00:00:00Z', to: '2024-03-01T00:00:00Z' });
+```
+
+`setVisibleTimeRange` is the one to reach for when syncing one chart's pan/zoom onto another
+**independent** `WickChart` instance that shares a time axis — a common pattern for a price
+chart and an indicator chart panned together, or any "these views move as one" UI. Indices
+aren't safe for this: two charts may have loaded different amounts of history via
+`setDataLoader`, so the same index means a different candle in each, while the same time
+always means the same point (or the nearest one either chart actually has loaded). A time
+value in `from`/`to` accepts every shape `Candle.time` does (unix seconds/ms, ISO string,
+`{ businessDay }}`); `getVisibleTimeRange()` always returns plain unix seconds.
+
+```ts
+// Keep `follower` in lockstep with `driver` — see demo/sync.html for a
+// complete two-chart example, including what to do about there being no
+// pan/zoom change event yet (see "Status" below).
+function syncLoop() {
+  const range = driver.getVisibleTimeRange();
+  if (range) follower.setVisibleTimeRange(range);
+  requestAnimationFrame(syncLoop);
+}
+```
+
+Both setters clamp an out-of-range request instead of throwing (the same way a drag/zoom
+gesture can never overscroll past the loaded data) and clear the current hover, since a jump
+is a discontinuous change — a hover position computed for the window before it no longer
+lines up with anything until the pointer moves again. Neither touches the value axis (manual
+price-range override, invert) — only the time window moves.
+
 ### Loading more history on demand
 
 `setDataLoader` lets you start with a small window and stream in more as the user pans toward
@@ -644,8 +716,13 @@ 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. `setVisibleRange`/`setVisibleTimeRange` let the pan/zoom window be set
+programmatically (see "Setting the visible range" above) — there's no pan/zoom *change* event
+yet, so keeping one chart synced to another (`demo/sync.html`) means polling
+`getVisibleTimeRange()` (e.g. once per animation frame) rather than reacting to a callback.
+See [CHANGELOG.md](./CHANGELOG.md) for what shipped in each release.
 
 ## License
 

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { DataLoader } from './dataSource.js';
 import type { ChartPlugin } from './plugins/types.js';
 import type { CandlestickStyle } from './series/candlestick.js';
 import type { LineStyle } from './series/line.js';
-import type { Candle, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange } from './types.js';
+import type { Candle, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange, WickTime } 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';
@@ -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;
     /**
@@ -150,6 +155,48 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
         endIndex: number;
         visibleCount: number;
     };
+    /**
+     * Jumps the visible pan/zoom window directly to `[startIndex, endIndex)`
+     * — the programmatic, index-based counterpart to `getVisibleRange()`'s
+     * own shape, for anything that already knows the target in index terms
+     * (a minimap click, a saved bookmark). Clamped the same way a drag/zoom
+     * gesture already is (see `Viewport.setVisibleIndexRange`) rather than
+     * throwing on an out-of-range request. Clears the current hover, the
+     * same way `setData()` does — a jump is a discontinuous change, and a
+     * hover position computed for the window before it is no longer
+     * meaningful until the pointer actually moves again.
+     *
+     * Indices aren't a safe way to sync two independent `WickChart`
+     * instances sharing a time axis — they may have loaded different
+     * amounts of history via `setDataLoader`, so the same index means a
+     * different point in each. Use `setVisibleTimeRange` for that instead.
+     */
+    setVisibleRange(range: {
+        startIndex: number;
+        endIndex: number;
+    }): this;
+    /**
+     * The time-based counterpart to `setVisibleRange` — jumps to whatever
+     * window of the currently loaded data falls within `[from, to]`
+     * (inclusive both ends), resolved against this chart's own loaded
+     * points. This is what makes syncing one chart's pan/zoom onto another
+     * independent `WickChart` instance sharing a time axis possible: read
+     * the source chart's `getVisibleTimeRange()` and pass it straight to
+     * this one, and the two stay in sync by time even if they've loaded
+     * different amounts of history. A no-op if no data has been loaded yet.
+     */
+    setVisibleTimeRange(range: {
+        from: WickTime;
+        to: WickTime;
+    }): this;
+    /** The currently visible window's time span, in unix seconds — `null`
+     * when there's no data to report one for. The time-based counterpart to
+     * `getVisibleRange()`, and the read side `setVisibleTimeRange` is meant
+     * to be paired with for syncing one chart's pan/zoom onto another. */
+    getVisibleTimeRange(): {
+        from: number;
+        to: number;
+    } | null;
     /** The value axis's manual range once the user has dragged or scaled it
      * — `null` if the axis is still auto-fitting to whatever's visible
      * (the default until the user first touches it vertically). */
@@ -157,6 +204,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';
@@ -44,6 +45,39 @@ const LONG_PRESS_MS = 350;
  * as a real drag, not a hold — cancels the pending long-press timer so a
  * fast pan gesture never flips into scrub mid-motion. */
 const LONG_PRESS_MOVE_TOLERANCE_PX = 10;
+/** First index in `times` (ascending) whose value is `>= target`, or
+ * `times.length` if every value is smaller — the standard binary
+ * lower-bound, O(log n) rather than a linear scan over what can be a
+ * multi-thousand-point loaded series. Used by `setVisibleTimeRange` to
+ * resolve a `from` time to its start index. */
+function lowerBound(times, target) {
+    let lo = 0;
+    let hi = times.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (times[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** First index in `times` (ascending) whose value is `> target`, or
+ * `times.length` if none is — the exclusive end boundary for a `to` time,
+ * so a range `[lowerBound(from), upperBound(to))` includes every point
+ * with a time in `[from, to]` inclusive on both ends. */
+function upperBound(times, target) {
+    let lo = 0;
+    let hi = times.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (times[mid] <= target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
 /**
  * Interactive chart: drag to pan, wheel to zoom, drag the price-axis strip
  * to rescale it, hover a point for a legend. What gets plotted (candles
@@ -302,6 +336,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
@@ -450,6 +485,62 @@ export class WickChart {
             visibleCount: this.viewport.visibleCount,
         };
     }
+    /**
+     * Jumps the visible pan/zoom window directly to `[startIndex, endIndex)`
+     * — the programmatic, index-based counterpart to `getVisibleRange()`'s
+     * own shape, for anything that already knows the target in index terms
+     * (a minimap click, a saved bookmark). Clamped the same way a drag/zoom
+     * gesture already is (see `Viewport.setVisibleIndexRange`) rather than
+     * throwing on an out-of-range request. Clears the current hover, the
+     * same way `setData()` does — a jump is a discontinuous change, and a
+     * hover position computed for the window before it is no longer
+     * meaningful until the pointer actually moves again.
+     *
+     * Indices aren't a safe way to sync two independent `WickChart`
+     * instances sharing a time axis — they may have loaded different
+     * amounts of history via `setDataLoader`, so the same index means a
+     * different point in each. Use `setVisibleTimeRange` for that instead.
+     */
+    setVisibleRange(range) {
+        this.viewport.setVisibleIndexRange(range.startIndex, range.endIndex, this.sorted.length);
+        this.hoverIndex = null;
+        this.hoverY = null;
+        this.scheduleRender();
+        return this;
+    }
+    /**
+     * The time-based counterpart to `setVisibleRange` — jumps to whatever
+     * window of the currently loaded data falls within `[from, to]`
+     * (inclusive both ends), resolved against this chart's own loaded
+     * points. This is what makes syncing one chart's pan/zoom onto another
+     * independent `WickChart` instance sharing a time axis possible: read
+     * the source chart's `getVisibleTimeRange()` and pass it straight to
+     * this one, and the two stay in sync by time even if they've loaded
+     * different amounts of history. A no-op if no data has been loaded yet.
+     */
+    setVisibleTimeRange(range) {
+        if (this.times.length === 0)
+            return this;
+        const fromSeconds = toUnixSeconds(range.from);
+        const toSeconds = toUnixSeconds(range.to);
+        return this.setVisibleRange({
+            startIndex: lowerBound(this.times, fromSeconds),
+            endIndex: upperBound(this.times, toSeconds),
+        });
+    }
+    /** The currently visible window's time span, in unix seconds — `null`
+     * when there's no data to report one for. The time-based counterpart to
+     * `getVisibleRange()`, and the read side `setVisibleTimeRange` is meant
+     * to be paired with for syncing one chart's pan/zoom onto another. */
+    getVisibleTimeRange() {
+        if (this.sorted.length === 0)
+            return null;
+        const startIdx = Math.max(0, Math.floor(this.viewport.startIndex));
+        const endIdx = Math.min(this.sorted.length, Math.ceil(this.viewport.endIndex));
+        if (endIdx <= startIdx)
+            return null;
+        return { from: this.times[startIdx], to: this.times[endIdx - 1] };
+    }
     /** The value axis's manual range once the user has dragged or scaled it
      * — `null` if the axis is still auto-fitting to whatever's visible
      * (the default until the user first touches it vertically). */
@@ -464,6 +555,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 +636,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 +789,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 +817,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/dist/viewport.d.ts

@@ -33,6 +33,17 @@ export declare class Viewport {
      * keeping the point at `anchorIndex` under the same relative position —
      * the standard "zoom toward the cursor" feel. */
     zoom(factor: number, anchorIndex: number, totalCount: number): void;
+    /**
+     * Replaces the visible window outright with `[startIndex, endIndex)`,
+     * clamped the same way `pan`/`zoom` already are (a floor on
+     * `visibleCount` so the window never collapses to nothing, and never
+     * extends past `[0, totalCount]`). The primitive a programmatic "jump to
+     * this range" builds on (see `WickChart.setVisibleRange`/
+     * `setVisibleTimeRange`) — unlike `pan`/`zoom`, which shift or scale the
+     * *current* window for a continuous gesture, this discards it and starts
+     * fresh from whatever was requested.
+     */
+    setVisibleIndexRange(startIndex: number, endIndex: number, totalCount: number): void;
     /** Multiplies the value-scale factor, clamped to a sane range so the
      * value axis can't be dragged into showing nothing or clipping data.
      * Only affects the auto-fit path — a no-op once `valueRangeOverride` is

package/dist/viewport.js

@@ -50,6 +50,22 @@ export class Viewport {
         const maxStart = Math.max(0, totalCount - this.visibleCount);
         this.startIndex = clamp(anchorIndex - anchorRatio * newVisibleCount, 0, maxStart);
     }
+    /**
+     * Replaces the visible window outright with `[startIndex, endIndex)`,
+     * clamped the same way `pan`/`zoom` already are (a floor on
+     * `visibleCount` so the window never collapses to nothing, and never
+     * extends past `[0, totalCount]`). The primitive a programmatic "jump to
+     * this range" builds on (see `WickChart.setVisibleRange`/
+     * `setVisibleTimeRange`) — unlike `pan`/`zoom`, which shift or scale the
+     * *current* window for a continuous gesture, this discards it and starts
+     * fresh from whatever was requested.
+     */
+    setVisibleIndexRange(startIndex, endIndex, totalCount) {
+        const requestedCount = endIndex - startIndex;
+        this.visibleCount = clamp(requestedCount, MIN_VISIBLE_COUNT, Math.max(totalCount, MIN_VISIBLE_COUNT));
+        const maxStart = Math.max(0, totalCount - this.visibleCount);
+        this.startIndex = clamp(startIndex, 0, maxStart);
+    }
     /** Multiplies the value-scale factor, clamped to a sane range so the
      * value axis can't be dragged into showing nothing or clipping data.
      * Only affects the auto-fit path — a no-op once `valueRangeOverride` is

package/package.json

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