@funnest/charts 0.0.0-stage → 0.1.0

package/dist/realtime.d.ts

@@ -0,0 +1,39 @@
+import type { Bar, Resolution } from './types';
+/** UTC offset (ms) of `timeZone` at instant `time`. Positive east of UTC (Asia/Seoul = +9h). */
+export declare function timeZoneOffset(time: number, timeZone: string): number;
+/**
+ * Start time of the bar that contains `time`.
+ * Intraday buckets align to the local clock; D/W/M align to local midnight
+ * (weeks start Monday). Pass the exchange's candle timezone — e.g. 'UTC' for
+ * Upbit/Binance daily candles, 'Asia/Seoul' for KRX.
+ */
+export declare function bucketStart(time: number, resolution: Resolution, timeZone?: string): number;
+export interface Tick {
+    /** Trade time, UTC ms. */
+    time: number;
+    price: number;
+    /** Traded quantity, added to the bar's volume. */
+    volume?: number;
+}
+/**
+ * Builds OHLCV bars from a trade/tick stream (e.g. Upbit `trade`, Binance `@trade`).
+ *
+ * ```ts
+ * const agg = new TickAggregator('1', 'UTC');
+ * agg.seed(lastHistoricalBar);              // continue the still-forming bar
+ * socket.onmessage = (m) => {
+ *   const bar = agg.push({ time: m.ts, price: m.price, volume: m.qty });
+ *   if (bar) onBar(bar);
+ * };
+ * ```
+ */
+export declare class TickAggregator {
+    readonly resolution: Resolution;
+    readonly timeZone: string;
+    private current;
+    constructor(resolution: Resolution, timeZone?: string);
+    /** Start from the latest historical bar so the first tick updates it instead of opening a new one. */
+    seed(bar: Bar | undefined): void;
+    /** Returns the updated bar, or null for a tick belonging to an already-closed bar. */
+    push(tick: Tick): Bar | null;
+}

package/dist/render/canvas-layer.d.ts

@@ -0,0 +1,13 @@
+/** A full-size canvas whose backing store tracks devicePixelRatio. Drawing uses CSS-pixel coordinates. */
+export declare class CanvasLayer {
+    readonly canvas: HTMLCanvasElement;
+    readonly ctx: CanvasRenderingContext2D;
+    width: number;
+    height: number;
+    dpr: number;
+    constructor(parent: HTMLElement);
+    resize(width: number, height: number, dpr: number): void;
+    /** Resets the transform to CSS pixels and clears. */
+    begin(): CanvasRenderingContext2D;
+    destroy(): void;
+}

package/dist/render/color-resolver.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Canvas can't read CSS variables, so `var(--x)` theme values are resolved through
+ * a hidden probe element living inside the chart (inheriting the host page's variables).
+ * Plain colors pass through untouched.
+ */
+export declare class ColorResolver {
+    private readonly probe;
+    private readonly cache;
+    constructor(probe: HTMLElement);
+    color(value: string): string;
+    fontFamily(value: string): string;
+    clear(): void;
+    private lookup;
+}

package/dist/render/painter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pixel-aligned drawing helpers. Lines are drawn as filled rects snapped to the
+ * device-pixel grid so they stay crisp at any devicePixelRatio.
+ */
+export declare class Painter {
+    readonly ctx: CanvasRenderingContext2D;
+    readonly dpr: number;
+    constructor(ctx: CanvasRenderingContext2D, dpr: number);
+    /** Thickness of a "1px" hairline: one whole device pixel (or more on high-DPR screens). */
+    get hairline(): number;
+    snap(v: number): number;
+    hLine(y: number, x1: number, x2: number, color: string, dash?: readonly [number, number]): void;
+    vLine(x: number, y1: number, y2: number, color: string, dash?: readonly [number, number]): void;
+    text(str: string, x: number, y: number, color: string, align?: CanvasTextAlign, baseline?: CanvasTextBaseline): void;
+    roundRect(x: number, y: number, w: number, h: number, r: number, color: string): void;
+    measure(str: string): number;
+    /** Anti-aliased line for arbitrary angles (trendlines). */
+    line(x1: number, y1: number, x2: number, y2: number, color: string, width?: number, dash?: readonly number[]): void;
+    circle(x: number, y: number, r: number, fill: string, stroke?: string, strokeWidth?: number): void;
+    /**
+     * A row of joined label segments ("pill") centered vertically on `y`.
+     * Returns each segment's rect for hit testing (e.g. an order's cancel button).
+     */
+    pill(segments: readonly PillSegment[], x: number, y: number, height?: number, radius?: number): Rect[];
+}
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface PillSegment {
+    text: string;
+    bg: string;
+    fg: string;
+    padding?: number;
+}
+export declare const inRect: (r: Rect, x: number, y: number, pad?: number) => boolean;

package/dist/render/renderer.d.ts

@@ -0,0 +1,100 @@
+import type { PriceScale } from '../model/price-scale';
+import type { TimeTick } from '../model/time-format';
+import type { IndexRange, TimeScale } from '../model/time-scale';
+import type { Bar } from '../types';
+import type { CanvasLayer } from './canvas-layer';
+import type { DrawingManager } from '../objects/drawings';
+import type { TradingLabels, TradingLayer } from '../objects/trading';
+import type { PaneCoords } from '../objects/types';
+import type { IndicatorOutput } from '../indicators/definitions';
+import type { ChartSettings } from '../settings';
+export type ChartType = 'candles' | 'line' | 'area';
+/** 'main', 'volume', or an indicator id for indicator panes. */
+export type PaneId = string;
+export interface PaneFrame {
+    id: PaneId;
+    kind: 'main' | 'volume' | 'indicator';
+    top: number;
+    height: number;
+    scale: PriceScale;
+    /** Values for grid lines and axis labels. */
+    ticks: number[];
+    /** Crosshair/value label format. */
+    format(value: number): string;
+    /** Axis tick label format (defaults to `format`). */
+    tickFormat?: (value: number) => string;
+    indicator?: IndicatorOutput;
+}
+export interface Palette {
+    background: string;
+    text: string;
+    textSecondary: string;
+    grid: string;
+    border: string;
+    crosshair: string;
+    up: string;
+    down: string;
+    accent: string;
+}
+/** Everything computed once per full frame; shared by the main and overlay passes. */
+export interface Frame {
+    width: number;
+    height: number;
+    plotWidth: number;
+    panesHeight: number;
+    timeAxisHeight: number;
+    panes: PaneFrame[];
+    range: IndexRange;
+    priceTicks: number[];
+    timeTicks: TimeTick[];
+    highLow: {
+        highIndex: number;
+        lowIndex: number;
+    } | null;
+    settings: ChartSettings;
+    /** Indicators drawn over the candles. */
+    overlays: IndicatorOutput[];
+    palette: Palette;
+    font: string;
+    radius: number;
+}
+export interface CrosshairInfo {
+    index: number;
+    time: number;
+    bar: Bar;
+    /** Price (main pane) or volume (volume pane) under the crosshair. */
+    value: number;
+    pane: PaneId;
+    x: number;
+    y: number;
+    source: 'mouse' | 'touch';
+}
+/** Fill details shown next to an execution marker. */
+export interface Tooltip {
+    x: number;
+    y: number;
+    side: 'buy' | 'sell';
+    lines: string[];
+}
+export interface RenderModel {
+    frame: Frame;
+    bars: readonly Bar[];
+    timeScale: TimeScale;
+    formatPrice(price: number): string;
+    formatVolume(volume: number): string;
+    formatCrosshairTime(time: number): string;
+    labels: {
+        high: string;
+        low: string;
+    };
+    chartType: ChartType;
+    objects: {
+        coords: PaneCoords;
+        drawings: DrawingManager;
+        trading: TradingLayer;
+        tradingLabels: TradingLabels;
+        barIndexAt(time: number): number;
+    };
+}
+export declare function drawMain(layer: CanvasLayer, m: RenderModel): void;
+export declare function drawOverlay(layer: CanvasLayer, m: RenderModel, ch: CrosshairInfo | null, tooltip?: Tooltip | null): void;

package/dist/resolution.d.ts

@@ -0,0 +1,8 @@
+import type { Resolution } from './types';
+export declare const DAY_MS = 86400000;
+/**
+ * Approximate duration of a resolution string.
+ * Bare numbers are minutes ('1', '15', '240'); suffixes: S (seconds), D, W, M (months ≈ 30d).
+ */
+export declare function resolutionToMs(resolution: Resolution): number;
+export declare function isIntradayResolution(resolution: Resolution): boolean;

package/dist/session.d.ts

@@ -0,0 +1,12 @@
+export interface SessionStatus {
+    /** Trading right now. Always true for '24x7'. */
+    open: boolean;
+    /** Next open/close transition (UTC ms); null for 24x7 markets. */
+    nextChange: number | null;
+}
+/**
+ * Parses sessions like '0900-1530' (weekdays, exchange-local time) or '24x7'.
+ * An optional day list may follow a colon using ISO weekdays: '0900-1530:12345'.
+ * Holidays aren't known here — feed them via a calendar adapter later (see ROADMAP).
+ */
+export declare function sessionStatus(session: string, timeZone: string, now?: number): SessionStatus;

package/dist/settings.d.ts

@@ -0,0 +1,40 @@
+import type { Drawing } from './objects/drawings';
+import type { IndicatorConfig } from './indicators/manager';
+import type { ChartType } from './render/renderer';
+import type { Resolution } from './types';
+/** User-facing chart preferences (the "차트 설정" dialog). */
+export interface ChartSettings {
+    /** "최고/최저" labels at the visible price extremes. */
+    highLowMarkers: boolean;
+    /** Dotted line and axis badge at the last price. */
+    lastPriceLine: boolean;
+    gridHorizontal: boolean;
+    gridVertical: boolean;
+    /** Volume pane under the price pane. */
+    volume: boolean;
+    /** Up/down candle colors; null follows the theme. */
+    upColor: string | null;
+    downColor: string | null;
+}
+export declare const DEFAULT_CHART_SETTINGS: ChartSettings;
+/**
+ * Everything needed to restore a chart layout: symbol, interval, chart type, settings,
+ * indicators, drawings (per symbol) and the visible window. Plain JSON — store it anywhere
+ * (localStorage, your server) and pass it back to `load()`.
+ */
+export interface ChartState {
+    version: 1;
+    symbol: string | null;
+    resolution: Resolution | null;
+    chartType: ChartType;
+    settings: ChartSettings;
+    indicators: IndicatorConfig[];
+    /** Drawings keyed by symbol ('' when the chart has no symbol, e.g. manual data). */
+    drawings: Record<string, Drawing[]>;
+    view: {
+        barSpacing: number;
+        rightOffset: number;
+    };
+}
+/** Validates untrusted JSON (e.g. from storage) into a ChartState; throws on an incompatible shape. */
+export declare function parseChartState(input: unknown): ChartState;

package/dist/theme.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Design tokens shared by the canvas engine and the DOM UI.
+ * Values may be any CSS color, including `var(--my-token)`; the engine
+ * resolves CSS variables against the chart container before painting.
+ */
+export interface ThemeTokens {
+    background: string;
+    surface: string;
+    text: string;
+    textSecondary: string;
+    grid: string;
+    border: string;
+    crosshair: string;
+    up: string;
+    down: string;
+    accent: string;
+    fontFamily: string;
+    fontSize: number;
+    radius: number;
+}
+export type DirectionPreset = 'kr' | 'global';
+export declare const lightTheme: ThemeTokens;
+export declare const darkTheme: ThemeTokens;
+export declare function createTheme(base: ThemeTokens, overrides?: Partial<ThemeTokens>, direction?: DirectionPreset): ThemeTokens;

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+/** A single OHLCV bar. `time` is the bar's open time in UTC milliseconds. */
+export interface Bar {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+/** Bar interval, e.g. '1', '5', '60' (minutes), '1D', '1W', '1M'. */
+export type Resolution = string;
+/** Minimum price increment. Either fixed, or price-dependent (e.g. KRX). */
+export type TickSize = number | ((price: number) => number);
+export interface SymbolInfo {
+    symbol: string;
+    name: string;
+    exchange: string;
+    /** IANA timezone, e.g. 'Asia/Seoul'. */
+    timezone: string;
+    /** Trading session, e.g. '0900-1530' or '24x7'. */
+    session: string;
+    /** Number of decimals to display. */
+    pricePrecision: number;
+    tickSize: TickSize;
+    volumePrecision?: number;
+    /** Optional logo shown next to the name in @funnest/charts-ui (falls back to an initial avatar). */
+    logoUrl?: string;
+    /** Instrument kind; drives search categories and which market stats make sense. */
+    type?: SymbolType;
+    /** ISO 3166 country of the listing ('KR', 'US'…), e.g. to split 국내/해외 stocks. */
+    country?: string;
+    /** Resolutions this symbol's feed can serve. Others are shown disabled in the UI. */
+    supportedResolutions?: Resolution[];
+}
+/**
+ * A search hit. Market fields are optional: return them when cheap (e.g. from a batch ticker)
+ * and the search list shows price, change and a sparkline next to each symbol.
+ */
+export interface SymbolSearchResult extends SymbolInfo {
+    price?: number;
+    changePercent?: number;
+    /** Recent closes, oldest first (~20–60 points) for the row sparkline. */
+    sparkline?: number[];
+}
+export type SymbolType = 'stock' | 'etf' | 'index' | 'crypto' | 'futures' | 'forex';
+/**
+ * Live market statistics for the market bar. Every field is optional: show what your
+ * venue has (spot has no open interest/funding, stocks have no 24h window…).
+ */
+export interface Quote {
+    price?: number;
+    /** Absolute change vs the reference (previous close / 24h ago). */
+    change?: number;
+    /** Change in percent, e.g. -1.23. */
+    changePercent?: number;
+    high24h?: number;
+    low24h?: number;
+    /** Traded quantity over 24h (or today for stocks). */
+    volume24h?: number;
+    /** Traded value in the quote currency (KRW, USDT…). */
+    turnover24h?: number;
+    /** Futures: open interest in contracts/base units. */
+    openInterest?: number;
+    /** Futures: current funding rate as a fraction (0.0001 = 0.01%). */
+    fundingRate?: number;
+    /** Futures: next funding time, UTC ms. */
+    nextFundingTime?: number;
+}
+export interface ConnectionState {
+    status: 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+    /** Round-trip latency estimate in ms, when the feed can measure it. */
+    latency?: number;
+}
+export interface BarsRequest {
+    from: number;
+    to: number;
+    /** Preferred number of bars ending at `to`; takes priority over `from` when set. */
+    countBack?: number;
+}
+export interface BarsResult {
+    bars: Bar[];
+    /** True when there is no older history to load. */
+    noMoreData: boolean;
+}
+export type Unsubscribe = () => void;
+/**
+ * Data source adapter. Implement this once per exchange/broker.
+ * Bars passed to `onBar` with the same `time` as the last bar update it;
+ * a greater `time` appends a new bar.
+ */
+export interface Datafeed {
+    resolveSymbol(symbol: string): Promise<SymbolInfo>;
+    getBars(symbol: SymbolInfo, resolution: Resolution, request: BarsRequest): Promise<BarsResult>;
+    /**
+     * Realtime updates. Call `onBar` with the current (forming) bar on every tick — the chart
+     * batches redraws per frame, so high message rates are fine. After a WebSocket reconnect,
+     * call `onResetCache` and the chart re-fetches the recent window via `getBars` to fill the gap.
+     */
+    subscribeBars(symbol: SymbolInfo, resolution: Resolution, onBar: (bar: Bar) => void, onResetCache?: () => void, 
+    /** Report the realtime connection's state/latency (shown in the status bar). */
+    onConnection?: (state: ConnectionState) => void): Unsubscribe;
+    /** Optional: powers the symbol search dialog in @funnest/charts-ui. */
+    searchSymbols?(query: string): Promise<SymbolSearchResult[]>;
+    /** Optional: live market statistics for the market bar. */
+    subscribeQuotes?(symbol: SymbolInfo, onQuote: (quote: Quote) => void): Unsubscribe;
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@funnest/charts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Canvas charting engine for financial charts",
+  "keywords": [
+    "chart",
+    "candlestick",
+    "trading",
+    "financial",
+    "canvas",
+    "krx",
+    "crypto",
+    "indicators"
+  ],
+  "license": "Apache-2.0",
+  "author": "Funnest",
+  "homepage": "https://charts.funnest.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funnest-xyz/funnest-charts.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/funnest-xyz/funnest-charts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "funnest-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }