@itssumitrai/fin-charter 0.2.0

package/dist/core/order-line.d.ts

@@ -0,0 +1,134 @@
+export type OrderSide = 'buy' | 'sell';
+export type OrderType = 'limit' | 'stop' | 'market';
+export type OrderModifiedCallback = (order: OrderLine) => void;
+export type OrderCancelledCallback = (order: OrderLine) => void;
+export interface OrderLineOptions {
+    price: number;
+    quantity: number;
+    side: OrderSide;
+    orderType: OrderType;
+    color?: string;
+    lineWidth?: number;
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+    title?: string;
+    draggable?: boolean;
+    axisLabelVisible?: boolean;
+}
+/**
+ * OrderLine represents a pending order on the chart (limit, stop, or market).
+ * It extends the concept of PriceLine with trading-specific properties such as
+ * quantity, side, order type, and drag-to-modify support.
+ */
+export declare class OrderLine {
+    readonly id: string;
+    private _price;
+    private _quantity;
+    private _side;
+    private _orderType;
+    private _color;
+    private _lineWidth;
+    private _lineStyle;
+    private _title;
+    private _draggable;
+    private _axisLabelVisible;
+    private _onModified;
+    private _onCancelled;
+    private _cancelled;
+    constructor(options: OrderLineOptions);
+    get price(): number;
+    get quantity(): number;
+    get side(): OrderSide;
+    get orderType(): OrderType;
+    get color(): string;
+    get lineWidth(): number;
+    get lineStyle(): 'solid' | 'dashed' | 'dotted';
+    get title(): string;
+    get draggable(): boolean;
+    get axisLabelVisible(): boolean;
+    get isCancelled(): boolean;
+    /** Update the order price (e.g. after a drag). Fires onModified callbacks. */
+    setPrice(price: number): void;
+    /** Update the order quantity. Fires onModified callbacks. */
+    setQuantity(quantity: number): void;
+    /** Apply partial option updates. Fires onModified callbacks. */
+    applyOptions(opts: Partial<OrderLineOptions>): void;
+    /** Cancel this order. Fires onCancelled callbacks. */
+    cancel(): void;
+    onModified(callback: OrderModifiedCallback): void;
+    offModified(callback: OrderModifiedCallback): void;
+    onCancelled(callback: OrderCancelledCallback): void;
+    offCancelled(callback: OrderCancelledCallback): void;
+    /** Serialize to a plain object for persistence. */
+    serialize(): {
+        id: string;
+        price: number;
+        quantity: number;
+        side: OrderSide;
+        orderType: OrderType;
+        color: string;
+        lineWidth: number;
+        lineStyle: string;
+        title: string;
+        draggable: boolean;
+        axisLabelVisible: boolean;
+    };
+    private _fireModified;
+}
+export interface PositionLineOptions {
+    entryPrice: number;
+    quantity: number;
+    side: OrderSide;
+    color?: string;
+    lineWidth?: number;
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+    title?: string;
+    axisLabelVisible?: boolean;
+}
+/**
+ * PositionLine represents an open trading position on the chart.
+ * It shows the entry price, quantity, and calculates unrealized P&L
+ * given a current market price.
+ */
+export declare class PositionLine {
+    readonly id: string;
+    private _entryPrice;
+    private _quantity;
+    private _side;
+    private _color;
+    private _lineWidth;
+    private _lineStyle;
+    private _title;
+    private _axisLabelVisible;
+    constructor(options: PositionLineOptions);
+    get entryPrice(): number;
+    get quantity(): number;
+    get side(): OrderSide;
+    get color(): string;
+    get lineWidth(): number;
+    get lineStyle(): 'solid' | 'dashed' | 'dotted';
+    get title(): string;
+    get axisLabelVisible(): boolean;
+    /**
+     * Calculate unrealized profit/loss given the current market price.
+     * Positive means profit, negative means loss.
+     */
+    unrealizedPnL(currentPrice: number): number;
+    /**
+     * Calculate unrealized P&L as a percentage of the entry value.
+     */
+    unrealizedPnLPercent(currentPrice: number): number;
+    /** Apply partial option updates. */
+    applyOptions(opts: Partial<PositionLineOptions>): void;
+    /** Serialize to a plain object for persistence. */
+    serialize(): {
+        id: string;
+        entryPrice: number;
+        quantity: number;
+        side: OrderSide;
+        color: string;
+        lineWidth: number;
+        lineStyle: string;
+        title: string;
+        axisLabelVisible: boolean;
+    };
+}

package/dist/core/pane-divider.d.ts

@@ -0,0 +1,22 @@
+export declare const DIVIDER_HEIGHT = 4;
+/**
+ * A draggable divider between two adjacent panes.
+ * On drag, redistributes height between the panes above and below.
+ */
+export declare class PaneDivider {
+    readonly el: HTMLDivElement;
+    private _getAboveHeight;
+    private _setAboveHeight;
+    private _getBelowHeight;
+    private _setBelowHeight;
+    private _onResize;
+    private _dragging;
+    private _startY;
+    private _startAboveH;
+    private _startBelowH;
+    constructor(getAboveHeight: () => number, setAboveHeight: (h: number) => void, getBelowHeight: () => number, setBelowHeight: (h: number) => void, onResize: () => void);
+    destroy(): void;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+}

package/dist/core/pane.d.ts

@@ -0,0 +1,32 @@
+import { PriceScale } from './price-scale';
+export interface PaneCanvases {
+    chartCanvas: HTMLCanvasElement;
+    overlayCanvas: HTMLCanvasElement;
+    rightPriceAxisCanvas: HTMLCanvasElement;
+    leftPriceAxisCanvas: HTMLCanvasElement;
+    chartCtx: CanvasRenderingContext2D;
+    overlayCtx: CanvasRenderingContext2D;
+    rightPriceAxisCtx: CanvasRenderingContext2D;
+    leftPriceAxisCtx: CanvasRenderingContext2D;
+    /** Optional WebGL canvas layered between chart and overlay canvases. */
+    webglCanvas?: HTMLCanvasElement;
+    webglCtx?: WebGL2RenderingContext;
+}
+/**
+ * Internal Pane class. Holds canvases, contexts, and price scales for a single pane row.
+ */
+export declare class Pane {
+    readonly id: string;
+    readonly row: HTMLDivElement;
+    readonly canvases: PaneCanvases;
+    readonly priceScale: PriceScale;
+    readonly leftPriceScale: PriceScale;
+    private _height;
+    constructor(id: string, height: number, useWebGL?: boolean);
+    get height(): number;
+    set height(value: number);
+    /**
+     * Layout all canvases within this pane row.
+     */
+    layout(chartW: number, leftScaleW: number, priceAxisWidth: number, rightScaleVisible: boolean, leftScaleVisible: boolean, pixelRatio: number): void;
+}

package/dist/core/periodicity.d.ts

@@ -0,0 +1,6 @@
+export interface Periodicity {
+    interval: number;
+    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month';
+}
+export declare function periodicityToSeconds(p: Periodicity): number;
+export declare function periodicityToLabel(p: Periodicity): string;

package/dist/core/plugin.d.ts

@@ -0,0 +1,90 @@
+/**
+ * IPlugin — formal plugin interface with lifecycle hooks.
+ *
+ * Plugins can add custom series types, indicators, drawing tools,
+ * UI panels, and intercept chart events.
+ */
+export interface IPlugin {
+    /** Unique plugin identifier. */
+    readonly name: string;
+    /** Plugin version (semver). */
+    readonly version?: string;
+    /** Plugins this plugin depends on (by name). */
+    readonly dependencies?: string[];
+    /**
+     * Called when the plugin is installed on a chart via chart.use(plugin).
+     * Receives the chart API for registering extensions.
+     */
+    install(chart: PluginChartApi): void;
+    /**
+     * Called when the plugin is uninstalled or the chart is destroyed.
+     */
+    uninstall?(): void;
+    /**
+     * Called on each paint cycle, after all series have been rendered.
+     * Allows plugins to render custom overlays.
+     */
+    onPaint?(context: PluginPaintContext): void;
+    /**
+     * Called when chart options change.
+     */
+    onOptionsChange?(options: Record<string, unknown>): void;
+    /**
+     * Called when data is updated on any series.
+     */
+    onDataUpdate?(): void;
+}
+/**
+ * Subset of the chart API exposed to plugins.
+ */
+export interface PluginChartApi {
+    /** Get the DOM container element. */
+    getContainer(): HTMLElement;
+    /** Request a chart repaint. */
+    requestRepaint(): void;
+    /** Get chart dimensions. */
+    getSize(): {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Context passed to plugin paint callbacks.
+ */
+export interface PluginPaintContext {
+    ctx: CanvasRenderingContext2D;
+    width: number;
+    height: number;
+    pixelRatio: number;
+}
+/**
+ * PluginManager — manages plugin lifecycle, dependency resolution,
+ * and event dispatch.
+ */
+export declare class PluginManager {
+    private _plugins;
+    private _installOrder;
+    private _chartApi;
+    /** Set the chart API reference. Called once during chart initialization. */
+    setChartApi(api: PluginChartApi): void;
+    /**
+     * Install a plugin. Resolves dependencies (must already be installed).
+     */
+    use(plugin: IPlugin): void;
+    /** Uninstall a plugin by name. */
+    remove(name: string): boolean;
+    /** Get an installed plugin by name. */
+    get(name: string): IPlugin | undefined;
+    /** List installed plugin names in install order. */
+    list(): string[];
+    /** Whether a plugin is installed. */
+    has(name: string): boolean;
+    /** Notify all plugins of a paint cycle. */
+    notifyPaint(context: PluginPaintContext): void;
+    /** Notify all plugins of options change. */
+    notifyOptionsChange(options: Record<string, unknown>): void;
+    /** Notify all plugins of data update. */
+    notifyDataUpdate(): void;
+    /** Uninstall all plugins in reverse order. */
+    removeAll(): void;
+}

package/dist/core/price-line.d.ts

@@ -0,0 +1,17 @@
+export interface PriceLineOptions {
+    price: number;
+    color: string;
+    lineWidth: number;
+    lineStyle: 'solid' | 'dashed' | 'dotted';
+    title: string;
+    axisLabelVisible: boolean;
+    axisLabelColor?: string;
+    axisLabelTextColor?: string;
+}
+export declare class PriceLine {
+    private _options;
+    private _requestRepaint;
+    constructor(options: PriceLineOptions, requestRepaint?: () => void);
+    get options(): Readonly<PriceLineOptions>;
+    applyOptions(opts: Partial<PriceLineOptions>, requestRepaint?: () => void): void;
+}

package/dist/core/price-scale.d.ts

@@ -0,0 +1,74 @@
+export type PriceScaleMode = 'linear' | 'logarithmic';
+export interface PriceRange {
+    min: number;
+    max: number;
+}
+export declare class PriceScale {
+    readonly position: 'left' | 'right';
+    private _height;
+    /** Current (animated) min/max used by priceToY. */
+    private _min;
+    private _max;
+    /** Target min/max that autoScale sets. Current values chase these. */
+    private _targetMin;
+    private _targetMax;
+    /** True after the first autoScale call — before that, we snap instead of animating. */
+    private _initialized;
+    /** True while current min/max are still converging toward target. */
+    private _animating;
+    /** When true, setRange() was called manually and autoScale() will not override it. */
+    private _manualRange;
+    private _comparisonMode;
+    private _mode;
+    constructor(position: 'left' | 'right');
+    /** Get the current scale mode. */
+    get mode(): PriceScaleMode;
+    /** Set the scale mode (linear or logarithmic). */
+    setMode(mode: PriceScaleMode): void;
+    setHeight(height: number): void;
+    /**
+     * Auto-scale to fit [minPrice, maxPrice].
+     * Margins are handled in coordinate conversion, not here.
+     * Ignored when a manual range is active.
+     *
+     * On the first call, values snap immediately. On subsequent calls,
+     * target values are set and current values animate toward them via tick().
+     */
+    autoScale(minPrice: number, maxPrice: number): void;
+    /**
+     * Advance the price scale animation by one frame.
+     * Returns true if still animating (caller should schedule another repaint).
+     */
+    tick(): boolean;
+    /** True while the scale is animating toward a new target range. */
+    get isAnimating(): boolean;
+    /** Reset animation state — snap current values to target immediately. */
+    snapToTarget(): void;
+    /**
+     * Manually override the price range.
+     * Subsequent autoScale() calls will be ignored until resetAutoScale() is called.
+     */
+    setRange(min: number, max: number): void;
+    /** Re-enable auto-scaling (next autoScale() call will take effect). */
+    resetAutoScale(): void;
+    /**
+     * Enable or disable comparison mode.
+     * In comparison mode the scale operates in "percent space" — callers pass
+     * percentage-change values (e.g. +12.5 for +12.5%) instead of raw prices.
+     * priceToY / yToPrice work identically; the caller is responsible for the
+     * raw-price → percentage conversion before calling priceToY.
+     */
+    setComparisonMode(enabled: boolean): void;
+    /** Returns true when comparison mode is active. */
+    isComparisonMode(): boolean;
+    /**
+     * Map a price to a y-pixel coordinate.
+     *
+     * In linear mode: equal vertical distance for equal price change.
+     * In logarithmic mode: equal vertical distance for equal percentage change.
+     */
+    priceToY(price: number): number;
+    /** Inverse of priceToY. */
+    yToPrice(y: number): number;
+    get priceRange(): PriceRange;
+}

package/dist/core/replay.d.ts

@@ -0,0 +1,73 @@
+import { Bar, ColumnStore } from './types';
+export type ReplaySpeed = 1 | 2 | 5 | 10;
+export type ReplayBarEvent = {
+    type: 'bar';
+    barIndex: number;
+    bar: Bar;
+};
+export type ReplayControlEvent = {
+    type: 'pause' | 'resume' | 'end';
+    barIndex: number;
+};
+export type ReplayEvent = ReplayBarEvent | ReplayControlEvent;
+export type ReplayEventCallback = (event: ReplayEvent) => void;
+export interface ReplayOptions {
+    /** Playback speed multiplier (default: 1). */
+    speed?: ReplaySpeed;
+}
+/**
+ * ReplayManager — steps through historical data bar-by-bar to simulate
+ * live data streaming. Bars appear progressively as if in real-time.
+ *
+ * Usage:
+ *   replay.start(store, fromIndex, { speed: 2 });
+ *   replay.onEvent(callback); // fired for each revealed bar or control event
+ *   replay.pause();
+ *   replay.stepForward();
+ *   replay.resume();
+ *   replay.stop();
+ */
+export declare class ReplayManager {
+    private _store;
+    private _currentIndex;
+    private _endIndex;
+    private _speed;
+    private _playing;
+    private _timerId;
+    private _callbacks;
+    private _baseIntervalMs;
+    /** Whether replay is currently active (playing or paused). */
+    get active(): boolean;
+    /** Whether replay is currently playing (not paused). */
+    get playing(): boolean;
+    /** Current bar index in the replay. */
+    get currentIndex(): number;
+    /** Current playback speed. */
+    get speed(): ReplaySpeed;
+    /** Subscribe to replay events. */
+    onEvent(callback: ReplayEventCallback): void;
+    /** Unsubscribe from replay events. */
+    offEvent(callback: ReplayEventCallback): void;
+    /**
+     * Start replay from the given bar index.
+     * Bars from 0 to fromIndex are initially visible; subsequent bars
+     * are revealed progressively.
+     */
+    start(store: ColumnStore, fromIndex: number, options?: ReplayOptions): void;
+    /** Pause playback. */
+    pause(): void;
+    /** Resume playback after pause. */
+    resume(): void;
+    /** Step forward one bar (works while paused or playing). */
+    stepForward(): boolean;
+    /** Step backward one bar (works while paused or playing). */
+    stepBackward(): boolean;
+    /** Set playback speed. */
+    setSpeed(speed: ReplaySpeed): void;
+    /** Stop replay and reset state. */
+    stop(): void;
+    private _startTimer;
+    private _stopTimer;
+    private _emitBar;
+    private _emit;
+}

package/dist/core/rtl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * RTL (Right-to-Left) layout building blocks.
+ *
+ * These utilities provide the foundation for RTL support. Chart-level
+ * integration (price axis flip, time axis mirroring, tooltip/menu layout)
+ * uses these helpers when the `direction` option is set.
+ */
+export type TextDirection = 'ltr' | 'rtl';
+/**
+ * Detect text direction from a locale string.
+ * Returns 'rtl' for Arabic, Hebrew, Persian, Urdu, and other RTL locales.
+ */
+export declare function detectDirection(locale: string): TextDirection;
+/**
+ * Mirror an X coordinate for RTL layout.
+ * In RTL mode, x=0 becomes x=width and vice versa.
+ */
+export declare function mirrorX(x: number, width: number, isRTL: boolean): number;
+/**
+ * Get the CSS text-align value for the current direction.
+ */
+export declare function resolveTextAlign(align: 'start' | 'end', isRTL: boolean): 'left' | 'right';

package/dist/core/segment-tree.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SegmentTree for O(log n) range min/max queries on Float64Array data.
+ *
+ * Supports incremental updates: when new data is appended, only the
+ * affected tree nodes are rebuilt — no full reconstruction needed.
+ */
+export declare class MinMaxSegmentTree {
+    private _minTree;
+    private _maxTree;
+    private _size;
+    private _n;
+    constructor(capacity: number);
+    get length(): number;
+    /**
+     * Build the tree from the given high/low arrays.
+     * O(n) time.
+     */
+    build(high: Float64Array, low: Float64Array, length: number): void;
+    /**
+     * Update a single index (e.g., when the last bar is modified).
+     * O(log n) time.
+     */
+    update(index: number, high: number, low: number): void;
+    /**
+     * Append a new value (for streaming data).
+     * O(log n) time.
+     */
+    append(high: number, low: number): void;
+    /**
+     * Query the min low and max high in the range [from, to] (inclusive).
+     * O(log n) time.
+     */
+    query(from: number, to: number): {
+        min: number;
+        max: number;
+    };
+    private _grow;
+}

package/dist/core/series-markers.d.ts

@@ -0,0 +1,18 @@
+export type MarkerShape = 'circle' | 'square' | 'arrowUp' | 'arrowDown';
+export type MarkerPosition = 'aboveBar' | 'belowBar' | 'inBar';
+export interface SeriesMarker {
+    time: number;
+    position: MarkerPosition;
+    shape: MarkerShape;
+    color: string;
+    text?: string;
+    size?: number;
+    id?: string;
+}
+export type EventType = 'earnings' | 'dividend' | 'split' | 'ipo' | 'other';
+export interface ChartEvent extends SeriesMarker {
+    eventType: EventType;
+    title: string;
+    description?: string;
+    value?: string;
+}

package/dist/core/storage-adapter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * IStorageAdapter — interface for persisting chart drawings and state.
+ *
+ * Implementations can use localStorage, IndexedDB, REST API, etc.
+ */
+export interface IStorageAdapter {
+    save(key: string, state: unknown): Promise<void>;
+    load(key: string): Promise<unknown | null>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * LocalStorageAdapter — persists data to browser localStorage.
+ */
+export declare class LocalStorageAdapter implements IStorageAdapter {
+    private _prefix;
+    constructor(prefix?: string);
+    save(key: string, state: unknown): Promise<void>;
+    load(key: string): Promise<unknown | null>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * IndexedDBAdapter — persists data to browser IndexedDB for larger state.
+ */
+export declare class IndexedDBAdapter implements IStorageAdapter {
+    private _dbName;
+    private _storeName;
+    private _dbPromise;
+    constructor(dbName?: string, storeName?: string);
+    private _getDB;
+    save(key: string, state: unknown): Promise<void>;
+    load(key: string): Promise<unknown | null>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * DrawingPersistence — manages auto-save/load of drawings per symbol.
+ */
+export declare class DrawingPersistence {
+    private _adapter;
+    private _debounceMs;
+    private _debounceTimer;
+    constructor(adapter: IStorageAdapter, debounceMs?: number);
+    /** Auto-save drawings for a symbol (debounced). */
+    saveDrawings(symbol: string, drawings: unknown): void;
+    /** Load drawings for a symbol. */
+    loadDrawings(symbol: string): Promise<unknown | null>;
+    /** Delete drawings for a symbol. */
+    deleteDrawings(symbol: string): Promise<void>;
+    /** Flush any pending debounced save immediately. */
+    flush(): void;
+}

package/dist/core/streaming-adapter.d.ts

@@ -0,0 +1,102 @@
+import { Bar } from './types';
+/**
+ * IStreamingAdapter — interface for real-time bar data streaming.
+ *
+ * Implementations connect to WebSocket, polling, or SSE endpoints
+ * and push bar updates to the chart via callbacks.
+ */
+export interface IStreamingAdapter {
+    /** Connect to the data source. */
+    connect(): void;
+    /** Disconnect and clean up. */
+    disconnect(): void;
+    /** Subscribe to real-time bar updates for a symbol/resolution. */
+    subscribeBars(symbol: string, resolution: string, onBar: (bar: Bar) => void): void;
+    /** Unsubscribe from bar updates. */
+    unsubscribeBars(symbol: string, resolution: string): void;
+}
+export interface WebSocketAdapterOptions {
+    /** WebSocket URL (e.g., 'wss://stream.example.com/bars'). */
+    url: string;
+    /** Auto-reconnect on disconnect (default: true). */
+    reconnect?: boolean;
+    /** Max reconnect attempts (default: 10, 0 = unlimited). */
+    maxReconnectAttempts?: number;
+    /** Initial reconnect delay in ms (default: 1000). Doubles each attempt. */
+    reconnectDelay?: number;
+    /** Max reconnect delay in ms (default: 30000). */
+    maxReconnectDelay?: number;
+    /**
+     * Parse an incoming WebSocket message into a Bar.
+     * Return null to skip the message.
+     */
+    parseMessage?: (data: unknown) => {
+        symbol: string;
+        resolution: string;
+        bar: Bar;
+    } | null;
+}
+type BarCallback = (bar: Bar) => void;
+/**
+ * WebSocketAdapter — streams bar data over a WebSocket connection
+ * with automatic reconnection and exponential backoff.
+ */
+export declare class WebSocketAdapter implements IStreamingAdapter {
+    private _options;
+    private _ws;
+    private _subscriptions;
+    private _reconnectAttempts;
+    private _reconnectTimer;
+    private _connected;
+    private _intentionalClose;
+    constructor(options: WebSocketAdapterOptions);
+    get connected(): boolean;
+    get reconnectAttempts(): number;
+    connect(): void;
+    disconnect(): void;
+    subscribeBars(symbol: string, resolution: string, onBar: BarCallback): void;
+    unsubscribeBars(symbol: string, resolution: string): void;
+    private _createConnection;
+    private _scheduleReconnect;
+    private _clearReconnectTimer;
+}
+export interface PollingAdapterOptions {
+    /** Fetch function that returns the latest bar for a symbol/resolution. */
+    fetchBar: (symbol: string, resolution: string) => Promise<Bar | null>;
+    /** Polling interval in ms (default: 5000). */
+    interval?: number;
+}
+/**
+ * PollingAdapter — polls a REST endpoint at regular intervals
+ * for the latest bar data.
+ */
+export declare class PollingAdapter implements IStreamingAdapter {
+    private _options;
+    private _interval;
+    private _timers;
+    private _subscriptions;
+    private _fetching;
+    constructor(options: PollingAdapterOptions);
+    connect(): void;
+    disconnect(): void;
+    subscribeBars(symbol: string, resolution: string, onBar: BarCallback): void;
+    unsubscribeBars(symbol: string, resolution: string): void;
+}
+/**
+ * TickBuffer — collects incoming ticks and flushes them at 60fps
+ * to avoid overwhelming the chart with per-tick repaints.
+ */
+export declare class TickBuffer {
+    private _buffer;
+    private _flushCallbacks;
+    private _rafId;
+    /** Register a flush callback for a symbol:resolution key. */
+    register(key: string, onFlush: BarCallback): void;
+    /** Unregister and stop flushing for a key. */
+    unregister(key: string): void;
+    /** Push a tick into the buffer (latest tick wins per key). */
+    push(key: string, bar: Bar): void;
+    private _startLoop;
+    private _stopLoop;
+}
+export {};