wick-charts 0.3.0

package/dist/hitTest.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Perpendicular distance, in px, from `(px, py)` to the line segment
+ * `(x1, y1)`-`(x2, y2)` — clamped to the segment itself, so a point beyond
+ * either endpoint measures against that endpoint rather than the infinite
+ * line the segment sits on.
+ *
+ * Every interactive plugin that draws a line-shaped thing (a trend line, a
+ * ray, an edge of a rectangle) eventually needs to answer "did the user
+ * click on/near the thing I already placed" so it can be selected, dragged,
+ * or deleted — and the endpoint-clamping is easy to get subtly wrong when
+ * re-derived per plugin, so it lives here once instead.
+ */
+export declare function distanceToSegment(px: number, py: number, x1: number, y1: number, x2: number, y2: number): number;
+/**
+ * `true` if `(px, py)` is within `tolerancePx` of the segment
+ * `(x1, y1)`-`(x2, y2)`. Defaults to 6px — comfortably clickable with a
+ * mouse pointer, still forgiving enough for an imprecise fingertip on
+ * touch. Call it from `onPointerDown`/`onPointerMove` with the event's
+ * `x`/`y` and the shape's own endpoints converted to pixels via the
+ * event's `xForIndex`/`yForValue` (a shape stored in data space survives
+ * pan/zoom; converting it to pixels at hit-test time, rather than storing
+ * pixels directly, is what keeps a placed line lined up with the candles
+ * it was drawn against after the user scrolls or zooms).
+ */
+export declare function hitTestSegment(px: number, py: number, x1: number, y1: number, x2: number, y2: number, tolerancePx?: number): boolean;
+/**
+ * `true` if `(px, py)` is within `tolerancePx` of the point `(x, y)` — for
+ * hit-testing a marker, a drag handle, or a single endpoint of a shape
+ * rather than an edge.
+ */
+export declare function hitTestPoint(px: number, py: number, x: number, y: number, tolerancePx?: number): boolean;

package/dist/hitTest.js

@@ -0,0 +1,46 @@
+/**
+ * Perpendicular distance, in px, from `(px, py)` to the line segment
+ * `(x1, y1)`-`(x2, y2)` — clamped to the segment itself, so a point beyond
+ * either endpoint measures against that endpoint rather than the infinite
+ * line the segment sits on.
+ *
+ * Every interactive plugin that draws a line-shaped thing (a trend line, a
+ * ray, an edge of a rectangle) eventually needs to answer "did the user
+ * click on/near the thing I already placed" so it can be selected, dragged,
+ * or deleted — and the endpoint-clamping is easy to get subtly wrong when
+ * re-derived per plugin, so it lives here once instead.
+ */
+export function distanceToSegment(px, py, x1, y1, x2, y2) {
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    const lengthSquared = dx * dx + dy * dy;
+    if (lengthSquared === 0)
+        return Math.hypot(px - x1, py - y1); // a zero-length "segment" is just a point
+    let t = ((px - x1) * dx + (py - y1) * dy) / lengthSquared;
+    t = Math.max(0, Math.min(1, t));
+    const closestX = x1 + t * dx;
+    const closestY = y1 + t * dy;
+    return Math.hypot(px - closestX, py - closestY);
+}
+/**
+ * `true` if `(px, py)` is within `tolerancePx` of the segment
+ * `(x1, y1)`-`(x2, y2)`. Defaults to 6px — comfortably clickable with a
+ * mouse pointer, still forgiving enough for an imprecise fingertip on
+ * touch. Call it from `onPointerDown`/`onPointerMove` with the event's
+ * `x`/`y` and the shape's own endpoints converted to pixels via the
+ * event's `xForIndex`/`yForValue` (a shape stored in data space survives
+ * pan/zoom; converting it to pixels at hit-test time, rather than storing
+ * pixels directly, is what keeps a placed line lined up with the candles
+ * it was drawn against after the user scrolls or zooms).
+ */
+export function hitTestSegment(px, py, x1, y1, x2, y2, tolerancePx = 6) {
+    return distanceToSegment(px, py, x1, y1, x2, y2) <= tolerancePx;
+}
+/**
+ * `true` if `(px, py)` is within `tolerancePx` of the point `(x, y)` — for
+ * hit-testing a marker, a drag handle, or a single endpoint of a shape
+ * rather than an edge.
+ */
+export function hitTestPoint(px, py, x, y, tolerancePx = 6) {
+    return Math.hypot(px - x, py - y) <= tolerancePx;
+}

package/dist/hybridScale.d.ts

@@ -0,0 +1,25 @@
+import type { WasmModule } from './wasm.js';
+/** Below this many points, a `LinearScale.mapMany` call is already just a
+ * handful of multiplications — crossing into WASM would spend more time on
+ * the JS↔WASM boundary than the JS version spends on the whole computation. */
+export declare const WASM_SCALE_THRESHOLD = 500;
+export interface Scale {
+    map(value: number): number;
+    mapMany(values: number[]): number[];
+}
+export interface DisposableScale {
+    scale: Scale;
+    dispose(): void;
+}
+/**
+ * Picks JS or WASM for a domain→range mapping based on how many points
+ * will go through it. `wasmModule` defaults to whatever `loadWasm` (see
+ * wasm.ts) has cached so far — pass it explicitly in tests instead of
+ * depending on that module-level cache.
+ *
+ * Always returns a `dispose()` — a no-op for the JS path, a real WASM
+ * memory free for the WASM path — so call sites can treat both uniformly
+ * (`try { ... } finally { result.dispose() }`) without branching on which
+ * one they got.
+ */
+export declare function createScale(domainMin: number, domainMax: number, rangeMin: number, rangeMax: number, pointCount: number, wasmModule?: WasmModule | null): DisposableScale;

package/dist/hybridScale.js

@@ -0,0 +1,41 @@
+import { LinearScale } from './scale.js';
+import { getCachedWasmModule } from './wasm.js';
+/** Below this many points, a `LinearScale.mapMany` call is already just a
+ * handful of multiplications — crossing into WASM would spend more time on
+ * the JS↔WASM boundary than the JS version spends on the whole computation. */
+export const WASM_SCALE_THRESHOLD = 500;
+/** A `Scale` backed by a `wasm-bindgen`-generated instance, freeing its
+ * WASM-side memory via `dispose()` — callers must call this once done
+ * (the renderer does so in a `finally`) since nothing else will. */
+class WasmBackedScale {
+    constructor(wasm, domainMin, domainMax, rangeMin, rangeMax) {
+        this.inner = new wasm.Scale(domainMin, domainMax, rangeMin, rangeMax);
+    }
+    map(value) {
+        return this.inner.map(value);
+    }
+    mapMany(values) {
+        return Array.from(this.inner.map_many(Float64Array.from(values)));
+    }
+    dispose() {
+        this.inner.free();
+    }
+}
+/**
+ * Picks JS or WASM for a domain→range mapping based on how many points
+ * will go through it. `wasmModule` defaults to whatever `loadWasm` (see
+ * wasm.ts) has cached so far — pass it explicitly in tests instead of
+ * depending on that module-level cache.
+ *
+ * Always returns a `dispose()` — a no-op for the JS path, a real WASM
+ * memory free for the WASM path — so call sites can treat both uniformly
+ * (`try { ... } finally { result.dispose() }`) without branching on which
+ * one they got.
+ */
+export function createScale(domainMin, domainMax, rangeMin, rangeMax, pointCount, wasmModule = getCachedWasmModule()) {
+    if (wasmModule && pointCount >= WASM_SCALE_THRESHOLD) {
+        const scale = new WasmBackedScale(wasmModule, domainMin, domainMax, rangeMin, rangeMax);
+        return { scale, dispose: () => scale.dispose() };
+    }
+    return { scale: new LinearScale(domainMin, domainMax, rangeMin, rangeMax), dispose: () => { } };
+}

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import type { DataLoader } from './dataSource.js';
+import type { ChartPlugin } from './plugins/types.js';
+import type { CandlestickStyle } from './series/candlestick.js';
+import type { Candle, WickChartOptions, SeriesPoint, ValueRange } from './types.js';
+export type { BusinessDay, Candle, 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';
+export type { Scale } from './hybridScale.js';
+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 { candlestickSeries } from './series/candlestick.js';
+export { LinearScale } from './scale.js';
+export { toUnixSeconds } from './time.js';
+export { Viewport } from './viewport.js';
+export { getCachedWasmModule, loadWasm } from './wasm.js';
+/**
+ * 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
+ * today; a future line/area/bar series) is decided entirely by
+ * `options.type` and the `SeriesDefinition` registered under it — this
+ * class only owns generic engine concerns (viewport math, mouse/touch/wheel
+ * handling, on-demand data loading, render scheduling) and never touches a
+ * point's fields directly. Construct once per canvas; call `destroy()`
+ * when done with it (unmount) to remove the window-level mouseup listener.
+ */
+export declare class WickChart<TPoint extends SeriesPoint = Candle> {
+    private canvas;
+    private renderer;
+    private seriesDefinition;
+    private sorted;
+    private times;
+    private viewport;
+    private hoverIndex;
+    /** Device-pixel y of the pointer/finger that produced `hoverIndex` — the
+     * crosshair's horizontal line follows this directly, not any property of
+     * the hovered point itself (see `ChartRenderer.renderCrosshairAndLegend`
+     * for why: pinning it to, say, the candle's close would leave the line
+     * motionless while the pointer moves within that candle's column). */
+    private hoverY;
+    private plugins;
+    /** The plugin whose `onPointerDown` returned `true` for the pointer
+     * currently down, or `null` when no plugin has claimed the current
+     * gesture (the common case — the chart handles it itself). */
+    private activeGesturePlugin;
+    private dragMode;
+    private lastX;
+    private lastY;
+    private renderScheduled;
+    private pendingAnimationFrame;
+    /** Distance (CSS px) between two touches on the previous touchmove —
+     * `null` whenever fewer than two fingers are down. Compared frame to
+     * frame (not against a fixed start value) so it composes naturally with
+     * the same incremental-delta style `applyPanDelta`/`applyValueScaleDelta`
+     * already use. */
+    private pinchLastDistance;
+    /** Where the current single-finger touch landed — compared against the
+     * live position to tell a hold from a drag; see LONG_PRESS_MOVE_TOLERANCE_PX. */
+    private touchStartX;
+    private touchStartY;
+    private longPressTimer;
+    private loader;
+    private loadThreshold;
+    private loading;
+    /** Set once a loader for a direction returns empty — stops re-asking at
+     * every threshold crossing until `setData` resets it (a fresh dataset
+     * may come from a different source that does have more). */
+    private exhausted;
+    constructor(canvas: HTMLCanvasElement, options?: WickChartOptions);
+    setData(points: TPoint[]): this;
+    /**
+     * Registers a callback the chart asks for more points when the visible
+     * window gets within `threshold` points of either edge of what's
+     * currently loaded. The chart never fetches on its own — it only decides
+     * *when* more data is needed and merges what the loader returns; the
+     * loader owns *how* (REST call, cache, websocket replay, whatever).
+     */
+    setDataLoader(loader: DataLoader<TPoint>, threshold?: number): this;
+    /** Registers a plugin (marker, annotation, drawing tool, ...) drawn on
+     * top of the chart every frame after the series and axes — see
+     * `src/plugins/types.ts`. Adding overlay features this way, rather than
+     * by extending `WickChart` itself, is what keeps the core closed to
+     * modification: a marker implementation never needs to touch this file. */
+    addPlugin(plugin: ChartPlugin<TPoint>): this;
+    removePlugin(plugin: ChartPlugin<TPoint>): this;
+    /** Every currently-registered plugin, in registration order — for an app
+     * building a management UI (a list of attached indicators/drawing tools
+     * with visibility toggles or delete buttons) without maintaining its own
+     * parallel bookkeeping of every `addPlugin` call. A copy, not a live
+     * view: mutating the returned array doesn't affect the chart. */
+    getPlugins(): readonly ChartPlugin<TPoint>[];
+    /** Shows or hides every plugin whose `id` matches (see `ChartPlugin.id`)
+     * and re-renders. A no-op, not an error, if nothing matches — plugins
+     * with no `id` set are never matched. */
+    setPluginVisible(id: string, visible: boolean): this;
+    render(): void;
+    /** Coalesces render() calls into at most one per animation frame. Mouse
+     * events (drag, wheel) can fire far faster than the display refreshes —
+     * calling render() directly from each one redraws the full canvas once
+     * per event instead of once per frame, which is what actually causes
+     * dragging to feel janky, not anything data-loading does. */
+    private scheduleRender;
+    /** How many points are currently loaded (not just visible) — grows as
+     * `setDataLoader`'s loader supplies more history. */
+    getPointCount(): number;
+    /** The currently visible window, in point indices into the full loaded
+     * series. Useful for building UI around the chart (a minimap, a "jump to
+     * latest" button) without reaching into private state. */
+    getVisibleRange(): {
+        startIndex: number;
+        endIndex: number;
+        visibleCount: number;
+    };
+    /** 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). */
+    getValueRangeOverride(): ValueRange | null;
+    /** The point currently under the cursor (crosshair/legend target), or
+     * `null` when nothing is hovered. */
+    getHoveredPoint(): TPoint | null;
+    /** 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. */
+    destroy(): void;
+    private attachEvents;
+    private onMouseDown;
+    private onMouseMove;
+    private onMouseUp;
+    private onMouseLeave;
+    /** Shared by both mouse drag and single-finger touch drag: shifts the
+     * visible time window and, once the value axis is in manual mode, the
+     * visible value window too — see the "pan" branch `onMouseMove` used to
+     * inline before mouse and touch needed the exact same math. */
+    private applyPanDelta;
+    /** Shared by both mouse drag and single-finger touch drag on the
+     * price-axis strip. */
+    private applyValueScaleDelta;
+    private onTouchStart;
+    private onTouchMove;
+    private onTouchEnd;
+    private clearLongPressTimer;
+    private touchDistance;
+    private onWheel;
+    private updateHover;
+    /** Checks whether the visible window is close enough to either edge of
+     * the loaded data to ask `this.loader` for more. Safe to call after
+     * every render — guarded so it never fires two overlapping requests for
+     * the same direction or re-asks a direction that already came back
+     * empty. */
+    private maybeLoadMore;
+    private requestMore;
+    private applyLoadedPoints;
+    /** Switches the price/value axis to manual mode if it hasn't been
+     * already, seeding it from the current auto-fit range so the first pixel
+     * of a drag doesn't jump. No-op on subsequent calls (already manual). */
+    private ensureValueRangeOverride;
+    /** The value range the *next* render would use — whatever's already
+     * manually overridden, or a fresh auto-fit computed the same way
+     * `ChartRenderer.render` does. Used outside of a render pass itself, by
+     * anything that needs to convert a pixel position to a data value
+     * on-demand (`valueForY`, dispatched pointer events) rather than only
+     * during `render()`. `null` when there's nothing to compute one from. */
+    private frameValueRange;
+    /** y pixel -> value in the range the next render would use. `null` if
+     * there's no data or no usable chart area to compute one against — see
+     * `ChartPointerEvent.value`. */
+    private valueForY;
+    /** x pixel -> global (possibly fractional) index — the exact inverse of
+     * the renderer's own `xForIndex`, so a pointer event lines up with
+     * wherever the chart itself would draw that index. */
+    private indexForX;
+    /** Global (possibly fractional) index -> x pixel — the exact inverse of
+     * `indexForX` above, and the same formula `ChartRenderer.render` draws
+     * with for the current viewport. Exposed on `ChartPointerEvent` so a
+     * plugin can convert a shape it's storing in data space back to pixels
+     * for hit-testing, without duplicating this math itself. */
+    private xForIndex;
+    /** Value in the range the next render would use -> y pixel — the exact
+     * inverse of `valueForY` above. `null` under the same conditions
+     * `valueForY` returns `null` for. */
+    private yForValue;
+    private pointerEventAt;
+    /** Same as `pointerEventAt`, but starting from `lastX`/`lastY` (raw
+     * `clientX`/`clientY`, tracked on every pointer move) instead of
+     * already-converted chart-area pixels — for the two touch-end paths
+     * where there's no current touch position to read coordinates from. */
+    private pointerEventAtLast;
+    /** Offers a pointer-down at `(x, y)` (chart-area pixels) to each plugin
+     * in reverse-registration order, stopping at the first one whose
+     * `onPointerDown` returns `true`. That plugin becomes
+     * `activeGesturePlugin` for the rest of the gesture; returns whether
+     * anyone claimed it, so callers know whether to skip their own default
+     * pan/price-scale handling. */
+    private dispatchPointerDown;
+    /** Position in canvas backing-store pixels, accounting for the gap
+     * between the canvas's CSS display size and its drawing-buffer size
+     * (e.g. when the canvas width attribute is device-pixel-ratio scaled).
+     * Takes any `{clientX, clientY}` point rather than `MouseEvent`
+     * specifically, since a `Touch` (or a synthesized pinch midpoint) has
+     * the same two fields and needs the exact same conversion. */
+    private cursorPosition;
+    /** CSS-pixel-to-backing-store-pixel ratio for the X axis — same
+     * conversion `cursorPosition` applies to absolute coordinates, extracted
+     * so pixel *deltas* (drag distance, wheel deltaX) can be converted too. */
+    private devicePixelScaleX;
+    private devicePixelScaleY;
+}
+/**
+ * `new WickChart(canvas, { type: 'candlestick', style: {...} })` type-checks
+ * even if `style` has nothing to do with `CandlestickStyle` — `type` is a
+ * runtime string the registry resolves, so nothing ties it to a specific
+ * `TStyle` at the type level (see `src/series/registry.ts`). This factory
+ * pins both `TPoint` (`Candle`) and `TStyle` (`CandlestickStyle`) for the
+ * one series built into the library, so `style` is fully checked here.
+ *
+ * A new series type gets the same treatment: export an equivalent
+ * `create<Name>Chart` next to it (in your own module, or a file like this
+ * one) rather than widening `WickChartOptions` itself — that keeps every
+ * series's style shape independent of every other's.
+ */
+export declare function createCandlestickChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style'> & {
+    style?: Partial<CandlestickStyle>;
+}): WickChart<Candle>;