@funnest/charts 0.5.1 → 0.6.0

package/dist/indicators/definitions.d.ts

@@ -1,6 +1,9 @@
 import type { Locale } from '../model/time-format';
 import type { Bar } from '../types';
-export type IndicatorType = 'ma' | 'ema' | 'bb' | 'rsi' | 'macd';
+/** Built-in indicators. */
+export type BuiltinIndicatorType = 'ma' | 'ema' | 'bb' | 'rsi' | 'macd';
+/** A built-in type, or the `type` of a definition passed in `ChartOptions.indicators`. */
+export type IndicatorType = BuiltinIndicatorType | (string & {});
 /** Which price an indicator reads from each bar. */
 export type PriceSource = 'close' | 'open' | 'high' | 'low' | 'hl2' | 'hlc3' | 'ohlc4';
 export declare const PRICE_SOURCES: {
@@ -39,14 +42,23 @@ export interface IndicatorSeries {
     width: number;
     visible: boolean;
     kind: 'line' | 'histogram';
+    /**
+     * Draw `values[i]` this many bars to the right (Ichimoku spans lead by 25). Points past the
+     * last bar land in the empty space on the right. Default 0.
+     */
+    shift?: number;
 }
 export interface IndicatorOutput {
     series: IndicatorSeries[];
-    /** Shaded area between two series (Bollinger band). */
+    /**
+     * Shaded area between two series (Bollinger band). With `downColor`, stretches where
+     * `lower` is above `upper` use it instead (Ichimoku cloud).
+     */
     fill?: {
         upper: string;
         lower: string;
         color: string;
+        downColor?: string;
     };
     /** Horizontal reference lines (RSI 30/70). */
     levels?: number[];
@@ -71,4 +83,4 @@ export declare const SERIES_COLORS: string[];
 export declare function priceSource(bars: readonly Bar[], source?: PriceSource): Float64Array;
 /** Reads `lines`, accepting the legacy `periods: number[]` shape too. */
 export declare function maLines(p: IndicatorParams): MaLine[];
-export declare const INDICATORS: Record<IndicatorType, IndicatorDefinition>;
+export declare const INDICATORS: Record<BuiltinIndicatorType, IndicatorDefinition>;

package/dist/indicators/manager.d.ts

@@ -1,5 +1,5 @@
 import type { Bar } from '../types';
-import { type IndicatorOutput, type IndicatorParams, type IndicatorType, type SeriesStyle } from './definitions';
+import { type IndicatorDefinition, type IndicatorOutput, type IndicatorParams, type IndicatorType, type SeriesStyle } from './definitions';
 export interface IndicatorConfig {
     id: string;
     type: IndicatorType;
@@ -10,13 +10,20 @@ export interface IndicatorConfig {
     styles?: Record<string, SeriesStyle>;
 }
 export type IndicatorPatch = Partial<Pick<IndicatorConfig, 'params' | 'visible' | 'styles'>>;
+/** Built-ins plus definitions passed to the chart (`ChartOptions.indicators`); later ones replace earlier ones of the same type. */
+export declare function indicatorRegistry(extra?: readonly IndicatorDefinition[]): Map<string, IndicatorDefinition>;
 /** Indicator instances plus a cache of computed series keyed by data version + settings. */
 export declare class IndicatorManager {
+    readonly registry: Map<string, IndicatorDefinition>;
     list: IndicatorConfig[];
     private readonly cache;
+    constructor(registry?: Map<string, IndicatorDefinition>);
+    def(type: IndicatorType): IndicatorDefinition;
+    private normalize;
     add(type: IndicatorType, params?: IndicatorParams): string;
     remove(id: string): boolean;
     update(id: string, patch: IndicatorPatch): boolean;
+    /** Unknown types (e.g. a plugin this chart wasn't given) are dropped. */
     set(configs: readonly IndicatorConfig[]): void;
     snapshot(): IndicatorConfig[];
     get overlays(): IndicatorConfig[];

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

@@ -4,10 +4,16 @@ export interface PriceScaleMargins {
     /** Fraction of pane height kept empty below the min price. */
     bottom: number;
 }
+/**
+ * 'normal': linear prices. 'log': equal distances are equal ratios. 'percent': linear, but labels
+ * show the change from a base price (the first visible bar's close).
+ */
+export type PriceScaleMode = 'normal' | 'log' | 'percent';
 /** Vertical scale for one pane. y is relative to the pane's top. */
 export declare class PriceScale {
     readonly margins: PriceScaleMargins;
     height: number;
+    mode: PriceScaleMode;
     /** Pixels reserved at the top for overlays (e.g. a legend); margins apply below it. */
     insetTop: number;
     autoScale: boolean;
@@ -21,13 +27,23 @@ export declare class PriceScale {
     private get available();
     private get innerTop();
     private get innerHeight();
+    /** Price → the space the axis is linear in (log prices in log mode). */
+    private toAxis;
+    private fromAxis;
     priceToY(price: number): number;
     yToPrice(y: number): number;
+    /** Sets the range in axis space (log prices in log mode). */
+    private setAxisRange;
     /** Scales around the center. factor > 1 shows a wider price range. Disables auto-scale. */
     zoom(factor: number): void;
     /** Moves the content by `dy` pixels (positive = content moves down). Disables auto-scale. */
     pan(dy: number): void;
 }
+/**
+ * Tick values for a log axis: roughly one per `spacing` px, each rounded to a nice step for the
+ * price distance at that height (1/2/2.5/5 × 10ⁿ, at least `minStep`). Spacing in price grows upward.
+ */
+export declare function logTicks(scale: PriceScale, spacing: number, minStep?: number): number[];
 /**
  * "Nice" tick values (1/2/2.5/5 × 10ⁿ) covering [min, max] with at most ~maxCount ticks.
  * `minStep` (e.g. the instrument's tick size) prevents sub-tick grid lines.

package/dist/objects/drawings.d.ts

@@ -1,5 +1,11 @@
+import type { Locale } from '../model/time-format';
+import type { Painter } from '../render/painter';
+import type { Palette } from '../render/renderer';
 import { type AxisBadge, type ObjectHit, type ObjectRenderContext, type PaneCoords } from './types';
-export type DrawingType = 'trendline' | 'horizontal' | 'fibonacci';
+/** Built-in drawing tools. */
+export type BuiltinDrawingType = 'trendline' | 'horizontal' | 'fibonacci';
+/** A built-in tool, or the `type` of a definition passed in `ChartOptions.drawings`. */
+export type DrawingType = BuiltinDrawingType | (string & {});
 export interface DrawingPoint {
     /** UTC ms — anchored to time, so drawings survive history loads and resolution changes. */
     time: number;
@@ -11,42 +17,92 @@ export interface Drawing {
     points: DrawingPoint[];
     color?: string;
 }
-export declare const DRAWING_POINTS: Record<DrawingType, number>;
+/** What a drawing definition gets to measure and paint itself. Pixels are relative to the price pane. */
+export interface DrawingGeometry {
+    coords: PaneCoords;
+    /** `drawing.points` in pane pixels. */
+    points: [number, number][];
+}
+export interface DrawingRenderContext extends DrawingGeometry {
+    painter: Painter;
+    palette: Palette;
+    /** `drawing.color`, or the theme accent. */
+    color: string;
+    /** Adds a price-axis badge (drawn above the axis labels, clamped to the pane). */
+    badge(y: number, text: string, bg: string, fg?: string): void;
+}
+/**
+ * A drawing tool. Built-ins use the same shape; pass your own in `ChartOptions.drawings` to add
+ * tools to the chart and the widget's drawing bar.
+ */
+export interface DrawingDefinition {
+    type: string;
+    name: Record<Locale, string>;
+    /**
+     * Drawing bar icon: SVG markup — either a whole `<svg>`, or just the shapes for a 20×20 viewBox
+     * drawn with `stroke="currentColor"` (like the built-in icons).
+     */
+    icon?: string;
+    /** Tools with the same group share one drawing-bar button with a menu. Default: the type. */
+    group?: string;
+    /** Clicks (or drag ends) needed to place it. */
+    clicks: number;
+    /**
+     * Turns the placed click points into the stored points, e.g. a position tool that creates
+     * entry/target/stop from one click. Called for the live preview too. Default: as placed.
+     */
+    create?(placed: DrawingPoint[], coords: PaneCoords): DrawingPoint[];
+    /** Keeps points consistent after point `index` was dragged (e.g. target and stop share a time). */
+    constrain?(points: DrawingPoint[], index: number): DrawingPoint[];
+    /** Drag handle positions; dragging handle i moves point i. Default: the points. */
+    handles?(geometry: DrawingGeometry): [number, number][];
+    /** Distance in px from (x, y) to the shape, for hit testing. */
+    distance(geometry: DrawingGeometry, x: number, y: number): number;
+    render(drawing: Drawing, rc: DrawingRenderContext): void;
+}
 export declare const FIB_LEVELS: number[];
+/** Distance from a point to the segment (x1,y1)–(x2,y2). Handy for `DrawingDefinition.distance`. */
+export declare function distToSegment(px: number, py: number, x1: number, y1: number, x2: number, y2: number): number;
+export declare const BUILTIN_DRAWINGS: readonly DrawingDefinition[];
+/** Built-ins plus definitions passed to the chart; later ones replace earlier ones of the same type. */
+export declare function drawingRegistry(extra?: readonly DrawingDefinition[]): Map<string, DrawingDefinition>;
 export type DrawingsChange = 'preview' | 'commit' | 'tool' | 'selection';
 /**
  * Owns drawings: creation (click-click or drag), selection, handle/body dragging,
  * hit testing and rendering. Pure state + canvas; pointer routing lives in Interaction.
+ * What each tool looks like comes from its DrawingDefinition.
  */
 export declare class DrawingManager {
     private readonly onChange;
+    readonly registry: Map<string, DrawingDefinition>;
     drawings: Drawing[];
     tool: DrawingType | null;
     selectedId: string | null;
     private draft;
     private drag;
-    constructor(onChange: (change: DrawingsChange) => void);
+    constructor(onChange: (change: DrawingsChange) => void, registry?: Map<string, DrawingDefinition>);
     get selected(): Drawing | null;
     setTool(tool: DrawingType | null): void;
     select(id: string | null): void;
+    /** Drawings of unknown types are kept (and saved) but not shown. */
     set(drawings: readonly Drawing[]): void;
     update(id: string, patch: Partial<Omit<Drawing, 'id'>>): void;
     remove(id: string): void;
     clear(): void;
     /** Esc: abort an in-progress drawing, else drop the tool, else deselect. */
     cancel(): void;
+    private expand;
     createAt(c: PaneCoords, x: number, y: number): void;
     /** Moves the not-yet-placed points (live preview while hovering or dragging). */
     previewAt(c: PaneCoords, x: number, y: number): void;
     /** Pointer released: a drag since the first point places the next one (drag-to-draw). */
     releaseAt(c: PaneCoords, x: number, y: number, moved: boolean): void;
     private finish;
+    private geometry;
+    private handles;
     hitTest(c: PaneCoords, x: number, y: number, tolerance: number): ObjectHit | null;
     beginDrag(c: PaneCoords, id: string, part: 'body' | number, x: number, y: number): void;
     dragTo(c: PaneCoords, x: number, y: number): void;
     endDrag(moved: boolean): void;
-    private screenPoints;
-    private distance;
     render(rc: ObjectRenderContext, badges: AxisBadge[]): void;
-    private renderOne;
 }

package/dist/objects/trading.d.ts

@@ -22,6 +22,16 @@ export interface OrderLineOptions {
     /** Shows an × button on the label. */
     onCancel?: () => void;
 }
+/** A price alert shown as a dotted line with a bell label. The alert logic itself is yours. */
+export interface AlertLineOptions {
+    price: number;
+    /** Overrides the default "알림" / "Alert" text. */
+    label?: string;
+    /** Called when the user drags the line; same contract as OrderLineOptions.onMove. */
+    onMove?: (price: number) => void | boolean | Promise<void | boolean>;
+    /** Shows an × button on the label. */
+    onCancel?: () => void;
+}
 export interface ExecutionMarker {
     time: number;
     price: number;
@@ -50,11 +60,13 @@ export interface TradingLabels {
     buy: string;
     sell: string;
     position: string;
+    alert: string;
 }
 /** Position (average price) lines, draggable order lines and execution markers. */
 export declare class TradingLayer {
     private readonly onChange;
     private readonly positions;
+    /** Order lines and alert lines (same dragging and × behavior). */
     private readonly orders;
     private executions;
     private labelRects;
@@ -63,6 +75,7 @@ export declare class TradingLayer {
     constructor(onChange: () => void);
     addPosition(options: PositionLineOptions): LineHandle<PositionLineOptions>;
     addOrder(options: OrderLineOptions): LineHandle<OrderLineOptions>;
+    addAlert(options: AlertLineOptions): LineHandle<AlertLineOptions>;
     setExecutions(markers: readonly ExecutionMarker[]): void;
     private handle;
     get executionList(): readonly ExecutionMarker[];

package/dist/objects/types.d.ts

@@ -5,6 +5,8 @@ export interface PaneCoords {
     plotWidth: number;
     height: number;
     timeToX(time: number): number;
+    /** Fractional bar index of `time` (extrapolated past either end), e.g. to count bars between points. */
+    timeToIndex(time: number): number;
     /** Point under (x, y): time snapped to the nearest bar (extrapolated into the future), price to the tick size. */
     pointAt(x: number, y: number): {
         time: number;

package/dist/render/renderer.d.ts

@@ -57,6 +57,8 @@ export interface Frame {
     palette: Palette;
     font: string;
     radius: number;
+    /** Time left in the current bar ("04:59"), shown under the last-price badge. */
+    countdown: string | null;
 }
 export interface CrosshairInfo {
     index: number;
@@ -89,6 +91,8 @@ export interface RenderModel {
         low: string;
     };
     chartType: ChartType;
+    /** Replay start picking: the area right of the crosshair is shaded. */
+    replaySelecting?: boolean;
     objects: {
         coords: PaneCoords;
         drawings: DrawingManager;

package/dist/settings.d.ts

@@ -1,5 +1,6 @@
 import type { Drawing } from './objects/drawings';
 import type { IndicatorConfig } from './indicators/manager';
+import type { PriceScaleMode } from './model/price-scale';
 import type { ChartType } from './render/renderer';
 import type { Resolution } from './types';
 /** User-facing chart preferences (the "차트 설정" dialog). */
@@ -14,6 +15,10 @@ export interface ChartSettings {
     volume: boolean;
     /** Zoom/scroll buttons at the bottom center of the chart (@funnest/charts-ui). */
     navigationButtons: boolean;
+    /** Price axis: linear prices, log scale, or % change from the first visible bar. Comparing symbols forces '%'. */
+    priceScale: PriceScaleMode;
+    /** Time left until the current bar closes, under the last-price badge. */
+    countdown: boolean;
     /** Up/down candle colors; null follows the theme. */
     upColor: string | null;
     downColor: string | null;
@@ -37,6 +42,8 @@ export interface ChartState {
         barSpacing: number;
         rightOffset: number;
     };
+    /** Symbols overlaid for comparison (see `Chart.addCompare`). */
+    compares?: string[];
 }
 /** Validates untrusted JSON (e.g. from storage) into a ChartState; throws on an incompatible shape. */
 export declare function parseChartState(input: unknown): ChartState;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnest/charts",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Canvas charting engine for financial charts",
   "keywords": [
     "chart",