wick-charts 0.6.0 → 0.7.0

package/README.md

@@ -21,6 +21,7 @@ npm install wick-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)
@@ -269,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
@@ -680,7 +718,11 @@ horizontal strip with an independent value axis — see "Multi-pane indicators"
 still shares the candlestick pane rather than getting its own, since it draws through the
 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.
+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';
@@ -155,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). */

package/dist/index.js

@@ -45,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
@@ -452,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). */

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