hyperprop-charting-library 0.1.135 → 0.1.137

package/dist/index.d.cts

@@ -91,6 +91,16 @@ interface ChartOptions {
 }
 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"
+/** 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
@@ -573,6 +583,15 @@ interface ChartInstance {
     onDrawingEditText: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     setMagnetMode: (mode: "none" | "weak" | "strong") => void;
     getMagnetMode: () => "none" | "weak" | "strong";
+    /**
+     * Change the price-scale mode ("linear" | "log" | "percent") and/or invert
+     * the axis. Log maps prices through log10, percent relabels the axis
+     * relative to the first visible bar's close (TradingView behavior), and
+     * invert flips the axis top-to-bottom. Only the main price pane is
+     * affected; indicator panes keep their own scales.
+     */
+    setPriceScale: (options: Partial<PriceScaleOptions>) => void;
+    getPriceScale: () => PriceScaleOptions;
     cancelDrawing: () => boolean;
     setTradeMarkers: (markers: TradeMarkerOptions[]) => void;
     onDrawingHover: (handler: ((event: DrawingHoverEvent) => void) | null) => void;
@@ -588,6 +607,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;
 }
@@ -611,6 +652,29 @@ 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";
+    /** Optional for backward compatibility with pre-0.1.137 blobs. */
+    priceScale?: PriceScaleOptions;
+    drawingDefaults: Partial<Record<DrawingToolType, DrawingDefaults>>;
+}
+type PriceScaleMode = "linear" | "log" | "percent";
+interface PriceScaleOptions {
+    mode: PriceScaleMode;
+    inverted: boolean;
+}
 
 interface ScriptIndicatorInputDef {
     key: string;
@@ -658,6 +722,45 @@ interface ScriptComputeResult {
     guides?: number[];
     decimals?: number;
 }
+interface ScriptInputOptions {
+    /** Stable settings key; defaults to a slug of the label. */
+    key?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+declare const SCRIPT_SOURCE_INPUT_VALUES: readonly ["open", "high", "low", "close", "hl2", "hlc3", "ohlc4"];
+/**
+ * The `input` object passed to script top level. In value mode it resolves
+ * each declaration against the current settings; in recording mode it
+ * additionally appends every declaration to `registry`. Keys are assigned
+ * deterministically (same order both modes), so values always line up with
+ * the extracted schema.
+ */
+declare const createScriptInputHelper: (values: Record<string, unknown> | null, registry: ScriptIndicatorInputDef[] | null) => Readonly<{
+    int: (label: string, defaultValue: number, options?: ScriptInputOptions) => number;
+    float: (label: string, defaultValue: number, options?: ScriptInputOptions) => number;
+    bool: (label: string, defaultValue?: boolean, options?: ScriptInputOptions) => boolean;
+    color: (label: string, defaultValue: string, options?: ScriptInputOptions) => string;
+    string: (label: string, defaultValue?: string, options?: ScriptInputOptions) => string;
+    select: (label: string, defaultValue: string, choices: ReadonlyArray<string | {
+        value: string;
+        label: string;
+    }>, options?: ScriptInputOptions) => string;
+    source: (label?: string, defaultValue?: string, options?: ScriptInputOptions) => string;
+}>;
+type ScriptInputHelper = ReturnType<typeof createScriptInputHelper>;
+/**
+ * Discover a script's Pine-style `input.*` declarations by running its top
+ * level with a recording helper. Returns the declared schema (empty when the
+ * script declares nothing) plus a compile/runtime error message when the
+ * script is broken. Runs under the standard execution guard, so an infinite
+ * top-level loop returns a budget error instead of hanging the caller.
+ */
+declare const extractScriptInputs: (source: string) => {
+    inputs: ScriptIndicatorInputDef[];
+    error: string | null;
+};
 /**
  * Compile-check a script without registering it: returns an error message, or
  * `null` when the script compiles. Runs with the same execution guard as the
@@ -678,4 +781,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 PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };

package/dist/index.d.ts

@@ -91,6 +91,16 @@ interface ChartOptions {
 }
 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"
+/** 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
@@ -573,6 +583,15 @@ interface ChartInstance {
     onDrawingEditText: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     setMagnetMode: (mode: "none" | "weak" | "strong") => void;
     getMagnetMode: () => "none" | "weak" | "strong";
+    /**
+     * Change the price-scale mode ("linear" | "log" | "percent") and/or invert
+     * the axis. Log maps prices through log10, percent relabels the axis
+     * relative to the first visible bar's close (TradingView behavior), and
+     * invert flips the axis top-to-bottom. Only the main price pane is
+     * affected; indicator panes keep their own scales.
+     */
+    setPriceScale: (options: Partial<PriceScaleOptions>) => void;
+    getPriceScale: () => PriceScaleOptions;
     cancelDrawing: () => boolean;
     setTradeMarkers: (markers: TradeMarkerOptions[]) => void;
     onDrawingHover: (handler: ((event: DrawingHoverEvent) => void) | null) => void;
@@ -588,6 +607,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;
 }
@@ -611,6 +652,29 @@ 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";
+    /** Optional for backward compatibility with pre-0.1.137 blobs. */
+    priceScale?: PriceScaleOptions;
+    drawingDefaults: Partial<Record<DrawingToolType, DrawingDefaults>>;
+}
+type PriceScaleMode = "linear" | "log" | "percent";
+interface PriceScaleOptions {
+    mode: PriceScaleMode;
+    inverted: boolean;
+}
 
 interface ScriptIndicatorInputDef {
     key: string;
@@ -658,6 +722,45 @@ interface ScriptComputeResult {
     guides?: number[];
     decimals?: number;
 }
+interface ScriptInputOptions {
+    /** Stable settings key; defaults to a slug of the label. */
+    key?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+declare const SCRIPT_SOURCE_INPUT_VALUES: readonly ["open", "high", "low", "close", "hl2", "hlc3", "ohlc4"];
+/**
+ * The `input` object passed to script top level. In value mode it resolves
+ * each declaration against the current settings; in recording mode it
+ * additionally appends every declaration to `registry`. Keys are assigned
+ * deterministically (same order both modes), so values always line up with
+ * the extracted schema.
+ */
+declare const createScriptInputHelper: (values: Record<string, unknown> | null, registry: ScriptIndicatorInputDef[] | null) => Readonly<{
+    int: (label: string, defaultValue: number, options?: ScriptInputOptions) => number;
+    float: (label: string, defaultValue: number, options?: ScriptInputOptions) => number;
+    bool: (label: string, defaultValue?: boolean, options?: ScriptInputOptions) => boolean;
+    color: (label: string, defaultValue: string, options?: ScriptInputOptions) => string;
+    string: (label: string, defaultValue?: string, options?: ScriptInputOptions) => string;
+    select: (label: string, defaultValue: string, choices: ReadonlyArray<string | {
+        value: string;
+        label: string;
+    }>, options?: ScriptInputOptions) => string;
+    source: (label?: string, defaultValue?: string, options?: ScriptInputOptions) => string;
+}>;
+type ScriptInputHelper = ReturnType<typeof createScriptInputHelper>;
+/**
+ * Discover a script's Pine-style `input.*` declarations by running its top
+ * level with a recording helper. Returns the declared schema (empty when the
+ * script declares nothing) plus a compile/runtime error message when the
+ * script is broken. Runs under the standard execution guard, so an infinite
+ * top-level loop returns a budget error instead of hanging the caller.
+ */
+declare const extractScriptInputs: (source: string) => {
+    inputs: ScriptIndicatorInputDef[];
+    error: string | null;
+};
 /**
  * Compile-check a script without registering it: returns an error message, or
  * `null` when the script compiles. Runs with the same execution guard as the
@@ -678,4 +781,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 PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };