@zuttora/charts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nishit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# chartZ (`@zuttora/charts`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zuttora's own charting package: candlesticks on an HTML canvas, square corners, no runtime
+dependencies. The full design is in Zuttora's `docs/charting.md` (section 6).
+
+```ts
+import { createChart, zuttoraTheme, INTERVAL_MS, IST_OFFSET_MS } from '@zuttora/charts';
+
+const chart = createChart(container, {   // the container must have a height
+  intervalMs: INTERVAL_MS['5m'],
+  tzOffsetMs: IST_OFFSET_MS,
+  priceDecimals: 2,
+  minMove: 0.05,
+  theme: { ...zuttoraTheme, fontFamily: resolvedFontFamily },
+});
+
+chart.setData(closedCandles, formingCandle, hasMore);   // Candle = { t, o, h, l, c }, t = slot start in epoch ms
+chart.applyTick(price, serverTime);                      // live prices: the last candle moves, slots roll over
+chart.on('needMore', (oldest) => { /* load older candles, then chart.prependData(older, hasMore) */ });
+chart.on('liveChange', (atLive) => { /* show or hide a "Go to live" button */ });
+```
+
+Also: `replaceClosed`, `setOptions`, `setPriceLines`, `setMarkers`, `scrollToLive`, `fitAll`, `destroy`.
+
+Gestures: drag to pan, wheel or pinch to zoom, press and hold (touch) or hover (mouse) for the
+crosshair, drag the price axis to scale it, double-click or double-tap to reset, arrow keys, `+`/`-`,
+`Home`, `End`.
+
+## Status
+
+| | |
+|---|---|
+| Core, rendering, interaction (M3 to M5) | done |
+| Indicators (M8) | `0.2.0` |
+| Published to npm | after review (needs the `NPM_TOKEN` secret) |
+
+## Develop
+
+```
+yarn install
+yarn typecheck && yarn lint && yarn test && yarn build && yarn size
+python3 -m http.server   # then open http://localhost:8000/demo/  (after yarn build)
+```
+
+Demo URL options: `?type=candles|line|area|heikinAshi&interval=1m|5m|10m|1h|3h|6h|1D&tick=200` (ms between fake ticks).
+
+Rules: no runtime dependencies, TypeScript that Node can run by stripping types (no `enum`,
+`namespace` or constructor parameter properties), relative imports with the `.ts` extension, no
+rounded corners, no `console` outside `src/core/warn.ts`.

package/dist/chart.d.ts

@@ -0,0 +1,8 @@
+import type { Chart, ChartOptions } from './core/types.ts';
+import type { ChartHost } from './host.ts';
+export type { ChartHost } from './host.ts';
+export interface ChartCore {
+    chart: Chart;
+    host: ChartHost;
+}
+export declare function createChartCore(container: HTMLElement, options: ChartOptions): ChartCore;

package/dist/chart.js

@@ -0,0 +1,214 @@
+import { Emitter } from "./core/emitter.js";
+import { buildDom } from "./dom/root.js";
+import { watchEnvironment } from "./dom/environment.js";
+import { syncLegend } from "./dom/legendSync.js";
+import { createHost } from "./host.js";
+import { createState, resolveOptions } from "./chartState.js";
+import { CLOSE_TWEEN_MS } from "./render/frameBuilder.js";
+import { paintFrame } from "./render/paintFrame.js";
+import { Scheduler } from "./render/scheduler.js";
+const perf = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+export function createChartCore(container, options) {
+    const doc = container.ownerDocument;
+    const s = createState(resolveOptions(options));
+    const events = new Emitter();
+    let destroyed = false;
+    let lastFrame = null;
+    const { root, mainCanvas, overlayCanvas, legend } = buildDom(doc, s.options.theme);
+    container.appendChild(root);
+    const applyAria = () => root.setAttribute('aria-label', s.options.ariaLabel);
+    const applyFocusRing = () => {
+        root.style.setProperty('--zc-focus', s.options.theme.accent);
+    };
+    applyAria();
+    applyFocusRing();
+    const updateLegend = () => syncLegend(s, legend);
+    const checkEvents = () => {
+        const live = s.vp.atLive();
+        if (live !== s.lastLive) {
+            s.lastLive = live;
+            events.emit('liveChange', live);
+        }
+        if (s.series.count > 0 && s.moreGate.check(s.vp.leftIndex(), s.series.hasMore)) {
+            events.emit('needMore', s.series.timeAt(0));
+        }
+    };
+    const draw = (flags, now) => {
+        if (destroyed)
+            return false;
+        return paintFrame(s, {
+            mainCanvas,
+            overlayCanvas,
+            dpr: () => env.dpr(),
+            frameBuilt: (f) => {
+                lastFrame = f;
+            },
+            afterDraw: checkEvents,
+        }, flags, now);
+    };
+    const scheduler = new Scheduler(draw);
+    const invalidate = (layer) => scheduler.invalidate(layer);
+    const invalidateAll = () => {
+        invalidate('main');
+        invalidate('overlay');
+    };
+    const resize = () => {
+        const r = container.getBoundingClientRect();
+        s.width = Math.max(0, Math.floor(r.width));
+        s.height = Math.max(0, Math.floor(r.height));
+        invalidateAll();
+    };
+    resize();
+    const env = watchEnvironment(container, doc, {
+        resize,
+        densityChanged: invalidateAll,
+        second: () => {
+            if (s.series.forming)
+                invalidate('overlay');
+        },
+        visible: invalidateAll,
+    });
+    const animNow = perf;
+    const chart = {
+        setData(closed, forming, hasMore) {
+            if (destroyed)
+                return;
+            const hadData = s.series.count > 0;
+            const wasLive = !hadData || s.vp.atLive();
+            const edge = Math.round(s.vp.rightIndex);
+            const frac = s.vp.rightIndex - edge;
+            const keepT = hadData && !wasLive ? s.series.timeAt(Math.min(edge, s.series.lastIndex())) : null;
+            s.series.setData(closed, forming, hasMore);
+            s.haBars.rebuild();
+            s.vp.setLastIndex(s.series.lastIndex());
+            s.moreGate.clear();
+            s.closeTween.jump(forming ? forming.c : 0);
+            s.rightAnimating = false;
+            if (keepT !== null) {
+                const i = s.series.indexAtTime(keepT);
+                if (i >= 0 && s.series.timeAt(i) === keepT)
+                    s.vp.setRightIndex(i + frac);
+                else
+                    s.vp.goLive();
+            }
+            else {
+                s.vp.goLive();
+            }
+            s.rangeReady = false;
+            updateLegend();
+            invalidateAll();
+        },
+        prependData(older, hasMore) {
+            if (destroyed)
+                return;
+            const added = s.series.prependData(older, hasMore);
+            if (added > 0) {
+                s.vp.onPrepend(added);
+                s.haBars.rebuild();
+            }
+            s.moreGate.clear();
+            updateLegend();
+            invalidateAll();
+        },
+        replaceClosed(candles) {
+            if (destroyed)
+                return;
+            if (s.series.replaceClosed(candles) > 0) {
+                s.haBars.rebuild();
+                updateLegend();
+                invalidateAll();
+            }
+        },
+        applyTick(price, time) {
+            if (destroyed)
+                return;
+            const r = s.series.applyTick(price, time, s.options.intervalMs, s.options.tzOffsetMs);
+            if (r.kind === 'ignored')
+                return;
+            const t = animNow();
+            if (r.kind === 'updated') {
+                s.closeTween.set(price, t, s.options.reducedMotion ? 0 : CLOSE_TWEEN_MS);
+            }
+            else {
+                if (r.kind === 'closed' && r.shifted > 0)
+                    s.vp.onShift(r.shifted);
+                s.vp.onAppend(s.series.lastIndex());
+                s.closeTween.jump(price);
+                s.haBars.rebuild();
+            }
+            s.haBars.refreshForming();
+            if (!s.options.reducedMotion && (s.options.type === 'line' || s.options.type === 'area')) {
+                s.pulses.push(t);
+                if (s.pulses.length > 8)
+                    s.pulses.shift();
+            }
+            if (r.kind === 'closed')
+                events.emit('candleClosed', r.closed);
+            if (!s.crosshair)
+                updateLegend();
+            invalidateAll();
+        },
+        setOptions(patch) {
+            if (destroyed)
+                return;
+            const next = resolveOptions({ ...s.options, ...patch, labels: { ...s.options.labels, ...patch.labels } });
+            s.options = next;
+            s.haBars.rebuild();
+            legend.applyTheme(next.theme);
+            applyAria();
+            applyFocusRing();
+            s.textWidths.clear();
+            s.rangeReady = false;
+            updateLegend();
+            invalidateAll();
+        },
+        setPriceLines(lines) {
+            if (destroyed)
+                return;
+            s.lines = lines.slice();
+            invalidate('main');
+        },
+        setMarkers(markers) {
+            if (destroyed)
+                return;
+            s.markers = markers.slice();
+            updateLegend();
+            invalidate('main');
+        },
+        scrollToLive() {
+            host.scrollToLive();
+        },
+        fitAll() {
+            if (destroyed)
+                return;
+            s.vp.fitAll();
+            s.rightAnimating = false;
+            invalidateAll();
+        },
+        on(event, listener) {
+            return events.on(event, listener);
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            scheduler.stop();
+            env.dispose();
+            events.clear();
+            host.dispose();
+            root.remove();
+        },
+    };
+    const host = createHost({
+        root,
+        state: s,
+        events,
+        invalidate,
+        invalidateAll,
+        updateLegend,
+        isDestroyed: () => destroyed,
+        lastFrame: () => lastFrame,
+        now: animNow,
+    });
+    return { chart, host };
+}

package/dist/chartState.d.ts

@@ -0,0 +1,41 @@
+import { CandleSeries } from './core/series.ts';
+import { PriceScale } from './core/priceScale.ts';
+import { MoreGate, Viewport } from './core/viewport.ts';
+import type { ChartLabels, ChartOptions, Marker, PriceLine } from './core/types.ts';
+import { HeikinBars, SeriesBars } from './render/bars.ts';
+import type { CrosshairInput } from './render/drawCrosshair.ts';
+import { Tween } from './render/tween.ts';
+export declare const DEFAULT_LABELS: ChartLabels;
+export interface ResolvedOptions extends Required<Omit<ChartOptions, 'labels' | 'ariaLabel' | 'now' | 'reducedMotion'>> {
+    labels: ChartLabels;
+    ariaLabel: string;
+    now: () => number;
+    reducedMotion: boolean;
+}
+export declare function resolveOptions(o: ChartOptions): ResolvedOptions;
+export interface ChartState {
+    options: ResolvedOptions;
+    series: CandleSeries;
+    vp: Viewport;
+    scale: PriceScale;
+    plainBars: SeriesBars;
+    haBars: HeikinBars;
+    moreGate: MoreGate;
+    lines: readonly PriceLine[];
+    markers: readonly Marker[];
+    rangeMin: Tween;
+    rangeMax: Tween;
+    rangeReady: boolean;
+    closeTween: Tween;
+    rightTween: Tween;
+    rightAnimating: boolean;
+    axisWidth: number;
+    textWidths: Map<string, number>;
+    width: number;
+    height: number;
+    crosshair: CrosshairInput | null;
+    pulses: number[];
+    lastLive: boolean;
+    lastCrosshairTime: number | null;
+}
+export declare function createState(options: ResolvedOptions): ChartState;

package/dist/chartState.js

@@ -0,0 +1,59 @@
+import { CandleSeries } from "./core/series.js";
+import { PriceScale } from "./core/priceScale.js";
+import { MoreGate, Viewport } from "./core/viewport.js";
+import { HeikinBars, SeriesBars } from "./render/bars.js";
+import { Tween } from "./render/tween.js";
+export const DEFAULT_LABELS = {
+    open: 'O',
+    high: 'H',
+    low: 'L',
+    close: 'C',
+    change: 'Change',
+    noData: 'No data yet',
+    heikinAshi: 'Heikin-Ashi (smoothed)',
+};
+export function resolveOptions(o) {
+    return {
+        intervalMs: o.intervalMs,
+        tzOffsetMs: o.tzOffsetMs,
+        priceDecimals: o.priceDecimals,
+        minMove: o.minMove ?? 10 ** -o.priceDecimals,
+        type: o.type ?? 'candles',
+        candleStyle: o.candleStyle ?? 'hollowUp',
+        theme: o.theme,
+        labels: { ...DEFAULT_LABELS, ...o.labels },
+        locale: o.locale ?? 'en-IN',
+        now: o.now ?? (() => Date.now()),
+        reducedMotion: o.reducedMotion ??
+            (typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches),
+        ariaLabel: o.ariaLabel ?? 'Price chart',
+    };
+}
+export function createState(options) {
+    const series = new CandleSeries();
+    return {
+        options,
+        series,
+        vp: new Viewport(),
+        scale: new PriceScale(),
+        plainBars: new SeriesBars(series),
+        haBars: new HeikinBars(series),
+        moreGate: new MoreGate(),
+        lines: [],
+        markers: [],
+        rangeMin: new Tween(0),
+        rangeMax: new Tween(1),
+        rangeReady: false,
+        closeTween: new Tween(0),
+        rightTween: new Tween(0),
+        rightAnimating: false,
+        axisWidth: 0,
+        textWidths: new Map(),
+        width: 0,
+        height: 0,
+        crosshair: null,
+        pulses: [],
+        lastLive: true,
+        lastCrosshairTime: null,
+    };
+}

package/dist/core/emitter.d.ts

@@ -0,0 +1,8 @@
+export declare class Emitter<Events extends {
+    [K in keyof Events]: (...args: never[]) => void;
+}> {
+    private map;
+    on<E extends keyof Events>(event: E, listener: Events[E]): () => void;
+    emit<E extends keyof Events>(event: E, ...args: Parameters<Events[E]>): void;
+    clear(): void;
+}

package/dist/core/emitter.js

@@ -0,0 +1,26 @@
+export class Emitter {
+    constructor() {
+        this.map = new Map();
+    }
+    on(event, listener) {
+        let set = this.map.get(event);
+        if (!set) {
+            set = new Set();
+            this.map.set(event, set);
+        }
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+        };
+    }
+    emit(event, ...args) {
+        const set = this.map.get(event);
+        if (!set)
+            return;
+        for (const fn of [...set])
+            fn(...args);
+    }
+    clear() {
+        this.map.clear();
+    }
+}

package/dist/core/format.d.ts

@@ -0,0 +1,9 @@
+export declare function priceFormatter(decimals: number, locale?: string): (value: number) => string;
+export declare function formatCountdown(msLeft: number): string;
+export interface ChangeParts {
+    direction: 1 | -1 | 0;
+    arrow: '▲' | '▼' | '';
+    amount: string;
+    percent: string;
+}
+export declare function changeParts(o: number, c: number, decimals: number, locale?: string): ChangeParts;

package/dist/core/format.js

@@ -0,0 +1,35 @@
+const formatters = new Map();
+export function priceFormatter(decimals, locale = 'en-IN') {
+    const key = `${locale}|${decimals}`;
+    let f = formatters.get(key);
+    if (!f) {
+        f = new Intl.NumberFormat(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+        formatters.set(key, f);
+    }
+    const fmt = f;
+    return (value) => fmt.format(value);
+}
+export function formatCountdown(msLeft) {
+    const total = Math.max(0, Math.ceil(msLeft / 1000));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    const ss = s < 10 ? `0${s}` : String(s);
+    if (h > 0)
+        return `${h}:${m < 10 ? '0' : ''}${m}:${ss}`;
+    return `${m}:${ss}`;
+}
+export function changeParts(o, c, decimals, locale = 'en-IN') {
+    const fmt = priceFormatter(decimals, locale);
+    const pctFmt = priceFormatter(2, locale);
+    const diff = c - o;
+    const direction = diff > 0 ? 1 : diff < 0 ? -1 : 0;
+    const pct = o !== 0 ? (diff / o) * 100 : 0;
+    const sign = direction > 0 ? '+' : direction < 0 ? '−' : '';
+    return {
+        direction,
+        arrow: direction > 0 ? '▲' : direction < 0 ? '▼' : '',
+        amount: `${sign}${fmt(Math.abs(diff))}`,
+        percent: `${sign}${pctFmt(Math.abs(pct))}%`,
+    };
+}

package/dist/core/heikinAshi.d.ts

@@ -0,0 +1,2 @@
+import type { Candle } from './types.ts';
+export declare function heikinAshi(candles: readonly Candle[]): Candle[];

package/dist/core/heikinAshi.js

@@ -0,0 +1,14 @@
+export function heikinAshi(candles) {
+    const out = [];
+    let prevO = 0;
+    let prevC = 0;
+    for (let i = 0; i < candles.length; i++) {
+        const k = candles[i];
+        const c = (k.o + k.h + k.l + k.c) / 4;
+        const o = i === 0 ? (k.o + k.c) / 2 : (prevO + prevC) / 2;
+        out.push({ t: k.t, o, h: Math.max(k.h, o, c), l: Math.min(k.l, o, c), c });
+        prevO = o;
+        prevC = c;
+    }
+    return out;
+}

package/dist/core/priceScale.d.ts

@@ -0,0 +1,22 @@
+import type { PriceLine } from './types.ts';
+export declare function niceStep(raw: number, minMove: number): number;
+export interface PriceRange {
+    min: number;
+    max: number;
+}
+export declare function autoRange(bars: PriceRange, extraValues: readonly number[], lines: readonly PriceLine[], minMove: number): PriceRange;
+export declare function pinSide(price: number, range: PriceRange): 'above' | 'below' | null;
+export declare function axisTicks(range: PriceRange, paneHeight: number, minMove: number): number[];
+export declare class PriceScale {
+    top: number;
+    height: number;
+    min: number;
+    max: number;
+    manual: boolean;
+    setPane(top: number, height: number): void;
+    setRange(range: PriceRange): void;
+    y(price: number): number;
+    priceAt(y: number): number;
+    scaleBy(dyPx: number): void;
+    resetAuto(): void;
+}

package/dist/core/priceScale.js

@@ -0,0 +1,92 @@
+export function niceStep(raw, minMove) {
+    const exp = Math.floor(Math.log10(raw));
+    const base = 10 ** exp;
+    const m = raw / base;
+    const nice = m <= 1 ? 1 : m <= 2 ? 2 : m <= 2.5 ? 2.5 : m <= 5 ? 5 : 10;
+    return Math.max(nice * base, minMove);
+}
+export function autoRange(bars, extraValues, lines, minMove) {
+    let min = bars.min;
+    let max = bars.max;
+    for (const v of extraValues) {
+        if (Number.isFinite(v)) {
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+    }
+    const span = max - min;
+    const lo = min - 0.5 * span;
+    const hi = max + 0.5 * span;
+    for (const line of lines) {
+        if (line.price >= lo && line.price <= hi) {
+            if (line.price < min)
+                min = line.price;
+            if (line.price > max)
+                max = line.price;
+        }
+    }
+    if (max === min) {
+        const pad = Math.max(Math.abs(max) * 0.001, 10 * minMove);
+        return { min: min - pad, max: max + pad };
+    }
+    const pad = (max - min) * 0.08;
+    return { min: min - pad, max: max + pad };
+}
+export function pinSide(price, range) {
+    if (price > range.max)
+        return 'above';
+    if (price < range.min)
+        return 'below';
+    return null;
+}
+export function axisTicks(range, paneHeight, minMove) {
+    const target = Math.max(2, Math.floor(paneHeight / 40));
+    const span = range.max - range.min;
+    if (!(span > 0))
+        return [];
+    const step = niceStep(span / target, minMove);
+    const out = [];
+    const first = Math.ceil(range.min / step - 1e-9);
+    for (let k = first; k * step <= range.max + step * 1e-9; k++) {
+        out.push(Math.round(k * step * 1e8) / 1e8);
+        if (out.length > 200)
+            break;
+    }
+    return out;
+}
+export class PriceScale {
+    constructor() {
+        this.top = 0;
+        this.height = 1;
+        this.min = 0;
+        this.max = 1;
+        this.manual = false;
+    }
+    setPane(top, height) {
+        this.top = top;
+        this.height = Math.max(1, height);
+    }
+    setRange(range) {
+        this.min = range.min;
+        this.max = range.max;
+    }
+    y(price) {
+        return this.top + ((this.max - price) / (this.max - this.min)) * this.height;
+    }
+    priceAt(y) {
+        return this.max - ((y - this.top) / this.height) * (this.max - this.min);
+    }
+    scaleBy(dyPx) {
+        const factor = Math.exp(dyPx * 0.005);
+        const centre = (this.max + this.min) / 2;
+        const half = ((this.max - this.min) / 2) * factor;
+        this.min = centre - half;
+        this.max = centre + half;
+        this.manual = true;
+    }
+    resetAuto() {
+        this.manual = false;
+    }
+}

package/dist/core/series.d.ts

@@ -0,0 +1,41 @@
+import type { Candle } from './types.ts';
+export declare const MAX_CLOSED = 5000;
+export type TickResult = {
+    kind: 'ignored';
+} | {
+    kind: 'updated';
+} | {
+    kind: 'started';
+} | {
+    kind: 'closed';
+    closed: Candle;
+    shifted: number;
+};
+export declare class CandleSeries {
+    t: number[];
+    o: number[];
+    h: number[];
+    l: number[];
+    c: number[];
+    forming: Candle | null;
+    hasMore: boolean;
+    get closedCount(): number;
+    get count(): number;
+    lastIndex(): number;
+    candleAt(i: number): Candle;
+    timeAt(i: number): number;
+    closeAt(i: number): number;
+    toArray(): Candle[];
+    setData(closed: readonly Candle[], forming: Candle | null, hasMore: boolean): void;
+    prependData(older: readonly Candle[], hasMore: boolean): number;
+    replaceClosed(candles: readonly Candle[]): number;
+    applyTick(price: number, time: number, intervalMs: number, offsetMs: number): TickResult;
+    visibleExtremes(from: number, to: number): {
+        min: number;
+        max: number;
+    } | null;
+    indexAtTime(time: number): number;
+    private closedIndexOf;
+    private push;
+    private dropOldest;
+}