hyperprop-charting-library 0.1.134 → 0.1.136

package/dist/index.d.cts

@@ -90,7 +90,25 @@ interface ChartOptions {
     drawings?: DrawingObjectOptions[];
 }
 type IndicatorPane = "overlay" | "separate";
-type DrawingToolType = "horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note";
+type DrawingToolType = "horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note"
+/** Three-point parallel channel: two clicks set the base line, a third sets the offset. */
+ | "parallel-channel"
+/** Two-anchor bounding-box ellipse (created like `rectangle`). */
+ | "ellipse"
+/** Trendline with an arrowhead at the second point. */
+ | "arrow"
+/** Freehand polyline: press and drag to draw, release to commit. */
+ | "brush"
+/** Text box with a connector line pointing at an anchored bar/price. */
+ | "callout"
+/**
+ * TradingView-style ruler. Unlike every other tool it is transient: the
+ * measurement overlay is never added to the drawings list (no
+ * `onDrawingsChange`), and it clears on the next click, on Escape, or when
+ * the tool changes. Also reachable without arming the tool via Shift+drag
+ * on the plot.
+ */
+ | "measure";
 interface DrawingPoint {
     index: number;
     price: number;
@@ -552,6 +570,14 @@ interface ChartInstance {
     removeDrawing: (id: string) => void;
     clearDrawings: () => void;
     onDrawingsChange: (handler: ((drawings: DrawingObjectOptions[]) => void) | null) => void;
+    /**
+     * Fires whenever the active drawing tool changes — including when the chart
+     * auto-reverts to the cursor after a tool completes (every drawing tool does
+     * this once its shape is placed; the transient `measure` tool does it after
+     * every measurement). Lets host toolbars stay in sync without polling
+     * `getActiveDrawingTool()`.
+     */
+    onActiveDrawingToolChange: (handler: ((tool: DrawingToolType | null) => void) | null) => void;
     onDrawingSelect: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingDoubleClick: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingEditText: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
@@ -572,6 +598,28 @@ interface ChartInstance {
     updateIndicator: (id: string, patch: Partial<IndicatorInstanceOptions>) => void;
     removeIndicator: (id: string) => void;
     setIndicators: (indicators: IndicatorInstanceOptions[]) => void;
+    /**
+     * Snapshot the full user-visible chart setup (chart type, viewport,
+     * drawings, indicators, magnet mode, drawing defaults) as one versioned,
+     * JSON-serializable blob. Persist it anywhere and restore with `loadState`.
+     */
+    saveState: () => ChartSavedState;
+    /**
+     * Restore a `saveState()` snapshot. Tolerant of partial blobs — missing
+     * sections are left untouched, so it also works as a bulk setter. Register
+     * any custom script indicator plugins *before* calling this, otherwise
+     * their instances are dropped with a console warning.
+     */
+    loadState: (state: Partial<ChartSavedState>) => void;
+    /**
+     * Render the current frame to an image data URL (default PNG). Everything
+     * drawn on the chart canvas is included — candles, indicators, drawings,
+     * legends — at the device pixel ratio the chart renders at.
+     */
+    takeScreenshot: (options?: {
+        type?: "image/png" | "image/jpeg";
+        quality?: number;
+    }) => string;
     resize: (width?: number, height?: number) => void;
     destroy: () => void;
 }
@@ -595,6 +643,22 @@ interface ViewportState {
     /** Manual Y-axis max override (null = auto-scale). */
     yMax: number | null;
 }
+/**
+ * Everything a host needs to persist to restore the user's chart setup with
+ * one `loadState()` call: series style, viewport, drawings, indicator
+ * instances, magnet mode and per-tool drawing defaults. Chart *data* is not
+ * included — feed bars through `setData` as usual. Custom (script) indicator
+ * plugins must be registered before `loadState` so their instances resolve.
+ */
+interface ChartSavedState {
+    version: 1;
+    chartType: ChartType;
+    viewport: ViewportState;
+    drawings: DrawingObjectOptions[];
+    indicators: IndicatorInstanceOptions[];
+    magnetMode: "none" | "weak" | "strong";
+    drawingDefaults: Partial<Record<DrawingToolType, DrawingDefaults>>;
+}
 
 interface ScriptIndicatorInputDef {
     key: string;
@@ -662,4 +726,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-export { type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartInstance, type ChartOptions, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, validateScriptSource };
+export { type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartInstance, type ChartOptions, type ChartSavedState, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, validateScriptSource };

package/dist/index.d.ts

@@ -90,7 +90,25 @@ interface ChartOptions {
     drawings?: DrawingObjectOptions[];
 }
 type IndicatorPane = "overlay" | "separate";
-type DrawingToolType = "horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note";
+type DrawingToolType = "horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note"
+/** Three-point parallel channel: two clicks set the base line, a third sets the offset. */
+ | "parallel-channel"
+/** Two-anchor bounding-box ellipse (created like `rectangle`). */
+ | "ellipse"
+/** Trendline with an arrowhead at the second point. */
+ | "arrow"
+/** Freehand polyline: press and drag to draw, release to commit. */
+ | "brush"
+/** Text box with a connector line pointing at an anchored bar/price. */
+ | "callout"
+/**
+ * TradingView-style ruler. Unlike every other tool it is transient: the
+ * measurement overlay is never added to the drawings list (no
+ * `onDrawingsChange`), and it clears on the next click, on Escape, or when
+ * the tool changes. Also reachable without arming the tool via Shift+drag
+ * on the plot.
+ */
+ | "measure";
 interface DrawingPoint {
     index: number;
     price: number;
@@ -552,6 +570,14 @@ interface ChartInstance {
     removeDrawing: (id: string) => void;
     clearDrawings: () => void;
     onDrawingsChange: (handler: ((drawings: DrawingObjectOptions[]) => void) | null) => void;
+    /**
+     * Fires whenever the active drawing tool changes — including when the chart
+     * auto-reverts to the cursor after a tool completes (every drawing tool does
+     * this once its shape is placed; the transient `measure` tool does it after
+     * every measurement). Lets host toolbars stay in sync without polling
+     * `getActiveDrawingTool()`.
+     */
+    onActiveDrawingToolChange: (handler: ((tool: DrawingToolType | null) => void) | null) => void;
     onDrawingSelect: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingDoubleClick: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingEditText: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
@@ -572,6 +598,28 @@ interface ChartInstance {
     updateIndicator: (id: string, patch: Partial<IndicatorInstanceOptions>) => void;
     removeIndicator: (id: string) => void;
     setIndicators: (indicators: IndicatorInstanceOptions[]) => void;
+    /**
+     * Snapshot the full user-visible chart setup (chart type, viewport,
+     * drawings, indicators, magnet mode, drawing defaults) as one versioned,
+     * JSON-serializable blob. Persist it anywhere and restore with `loadState`.
+     */
+    saveState: () => ChartSavedState;
+    /**
+     * Restore a `saveState()` snapshot. Tolerant of partial blobs — missing
+     * sections are left untouched, so it also works as a bulk setter. Register
+     * any custom script indicator plugins *before* calling this, otherwise
+     * their instances are dropped with a console warning.
+     */
+    loadState: (state: Partial<ChartSavedState>) => void;
+    /**
+     * Render the current frame to an image data URL (default PNG). Everything
+     * drawn on the chart canvas is included — candles, indicators, drawings,
+     * legends — at the device pixel ratio the chart renders at.
+     */
+    takeScreenshot: (options?: {
+        type?: "image/png" | "image/jpeg";
+        quality?: number;
+    }) => string;
     resize: (width?: number, height?: number) => void;
     destroy: () => void;
 }
@@ -595,6 +643,22 @@ interface ViewportState {
     /** Manual Y-axis max override (null = auto-scale). */
     yMax: number | null;
 }
+/**
+ * Everything a host needs to persist to restore the user's chart setup with
+ * one `loadState()` call: series style, viewport, drawings, indicator
+ * instances, magnet mode and per-tool drawing defaults. Chart *data* is not
+ * included — feed bars through `setData` as usual. Custom (script) indicator
+ * plugins must be registered before `loadState` so their instances resolve.
+ */
+interface ChartSavedState {
+    version: 1;
+    chartType: ChartType;
+    viewport: ViewportState;
+    drawings: DrawingObjectOptions[];
+    indicators: IndicatorInstanceOptions[];
+    magnetMode: "none" | "weak" | "strong";
+    drawingDefaults: Partial<Record<DrawingToolType, DrawingDefaults>>;
+}
 
 interface ScriptIndicatorInputDef {
     key: string;
@@ -662,4 +726,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-export { type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartInstance, type ChartOptions, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, validateScriptSource };
+export { type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartInstance, type ChartOptions, type ChartSavedState, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, validateScriptSource };