openalgo-charts 2.4.5 → 2.4.7

package/README.md

@@ -4,12 +4,12 @@
 
 **A from-scratch, dependency-free HTML5-canvas charting engine for OpenAlgo.**
 
-Professional interactive charts, 105 built-in indicators plus your own custom ones, 85 drawing tools, order flow, market replay, linked chart grids, on-chart trading, vector SVG export and an optional WebGL2 backend. Nine lazy-loaded tiers, zero runtime dependencies, 91.00 kB Brotli for the base engine, and a one-call widget tier that adds the toolbar, drawing rail, dialogs and shortcuts.
+Professional interactive charts, 105 built-in indicators plus your own custom ones, 85 drawing tools, order flow, market replay, linked chart grids, on-chart trading, vector SVG export and an optional WebGL2 backend. Nine lazy-loaded tiers, zero runtime dependencies, 92.83 kB Brotli for the base engine, and a one-call widget tier that adds the toolbar, drawing rail, dialogs and shortcuts.
 
 [![npm version](https://img.shields.io/npm/v/openalgo-charts.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/openalgo-charts)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
-[![bundle](https://img.shields.io/badge/brotli-91.00%20kB%20base%20%C2%B7%20243.96%20kB%20all%20tiers-brightgreen.svg)](#size-budget)
-[![tests](https://img.shields.io/badge/engine%20tests-5734%20passing-brightgreen.svg)](#develop)
+[![bundle](https://img.shields.io/badge/brotli-92.83%20kB%20base%20%C2%B7%20246.52%20kB%20all%20tiers-brightgreen.svg)](#size-budget)
+[![tests](https://img.shields.io/badge/engine%20tests-5841%20passing-brightgreen.svg)](#develop)
 [![dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](#principles)
 
 [**Documentation**](https://marketcalls.github.io/openalgo-charts/)  ·  [**Live examples**](https://marketcalls.github.io/openalgo-charts/examples)  ·  [**Getting started**](./docs/getting-started.md)  ·  [**Migrating to 2.0**](./docs/migrating-to-2.md)  ·  [**Architecture**](./ARCHITECTURE.md)
@@ -53,13 +53,16 @@ Every chart in the [live gallery](https://marketcalls.github.io/openalgo-charts/
 
 ## Install
 
-Current version: **2.4.5**.
+Current version: **2.4.7**.
 
-This release adds validated instrument metadata, adapter conformance checks,
-browser endurance tooling, translated widget controls and trading capability
-checks. Named workspace documents and indicator templates use an optional
-asynchronous storage tier. Existing hosts can adopt these contracts incrementally.
-See the [2.4.5 changelog](./CHANGELOG.md#245).
+Drag a price or study-threshold alert line to preview a new level, then release
+to save it once. Escape cancels the draft; range bounds stay ordered. Stored
+thresholds and live evaluation remain unchanged during preview. See the
+[2.4.7 changelog](./CHANGELOG.md#247) and the [live example](https://marketcalls.github.io/openalgo-charts/examples/#alert-threshold-dragging).
+
+To try dragging locally, run the [yfinance reference host](./examples/yfinance/README.md),
+create a price alert from the chart context menu, and drag its dashed line or
+**Alert** badge. Study and range alerts use the same controls.
 
 ```bash
 npm install openalgo-charts
@@ -88,7 +91,7 @@ in front of npm rather than being places you upload to. A chart is one HTML file
 ```html
 <div id="chart" style="width:100vw;height:100vh"></div>
 <script type="module">
-  import { createChart } from 'https://unpkg.com/openalgo-charts@2.4.5/dist/openalgo-charts.mjs';
+  import { createChart } from 'https://unpkg.com/openalgo-charts@2.4.7/dist/openalgo-charts.mjs';
   const chart = createChart(document.getElementById('chart'), { timezone: 'Asia/Kolkata' });
   chart.addSeries('candlestick').setData(bars);
 </script>
@@ -130,17 +133,17 @@ Import only what you use. Each tier is a separate bundle that registers into the
 
 | Import | Contents | Brotli |
 |---|---|---|
-| `openalgo-charts` | Engine, 13 chart types, panes &amp; scales, primitives, registries, chart state, chart linking, bar cache, interval registry, trading overlay, SVG export, render backend port, OpenAlgo feeds | 91.00 kB |
+| `openalgo-charts` | Engine, 13 chart types, panes &amp; scales, primitives, registries, chart state, chart linking, bar cache, interval registry, trading overlay, SVG export, render backend port, OpenAlgo feeds | 92.83 kB |
 | `openalgo-charts/indicators` | 105 built-in indicators, the `registerIndicator` contract for your own, and the Tier-2 (external-data) contract | 29.84 kB |
 | `openalgo-charts/draw` | 85 drawing tools + a headless drawing controller, clipboard, settings schema, level palette, freehand geometry and SVG icons | 35.43 kB |
 | `openalgo-charts/transform` | Heikin Ashi, Renko, Range bars, Line Break, Point &amp; Figure, Kagi, and symbol arithmetic (`AAPL/MSFT`) | 4.50 kB |
 | `openalgo-charts/profile` | Volume Profile, Market Profile (TPO) with compact pixel letters, Footprint, order flow | 14.96 kB |
 | `openalgo-charts/trade` | Order / position / bracket tools + DOM ladder | 8.01 kB |
 | `openalgo-charts/webgl` | WebGL2 series backend: batched, analytically anti-aliased GPU rendering of the standard chart types behind `renderer: 'auto'`, with a session-long fallback to the 2D path | 6.39 kB |
-| `openalgo-charts/widget` | The chart with its chrome in one call: `createWidget` adds a top bar, the drawing rail, a status line, the settings and indicator dialogs, drawing properties, a right-click menu, a keymap with a `?` panel and optional layout persistence. The only tier that ships DOM | 48.30 kB |
+| `openalgo-charts/widget` | The chart with its chrome in one call: `createWidget` adds a top bar, the drawing rail, a status line, the settings and indicator dialogs, drawing properties, a right-click menu, a keymap with a `?` panel and optional layout persistence. The only tier that ships DOM | 49.03 kB |
 | `openalgo-charts/workspace` | Validated workspace and indicator-template documents, named catalogs with revision checks, asynchronous storage and an IndexedDB adapter; no DOM | 5.52 kB |
 
-Everything together is **243.96 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 204.58 kB. Figures are measured from the 2.4.5 release build. The trade tier is 8.01 kB on its own; base + trade costs 99.01 kB. Sizes use decimal kB.
+Everything together is **246.52 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 207.13 kB. Figures are measured from the 2.4.7 release build. The trade tier is 8.01 kB on its own; base + trade costs 100.84 kB. Sizes use decimal kB.
 
 ## What's built
 
@@ -445,17 +448,17 @@ Enforced in CI by [`size-limit`](./.size-limit.json). Nothing is excluded, becau
 
 | Bundle | Limit | Actual |
 |---|---|---|
-| Base engine | 91.5 kB | 91.00 kB |
-| Base + trade | 100 kB | 99.01 kB |
+| Base engine | 93.5 kB | 92.83 kB |
+| Base + trade | 101.5 kB | 100.84 kB |
 | Indicators tier | 30 kB | 29.84 kB |
 | Draw tier | 36 kB | 35.43 kB |
 | Transform tier | 6 kB | 4.50 kB |
 | Profile tier | 15 kB | 14.96 kB |
 | WebGL2 tier | 7 kB | 6.39 kB |
-| Widget tier | 48.75 kB | 48.30 kB |
-| Widget terminal (base + draw + indicators + widget) | 205 kB | 204.58 kB |
+| Widget tier | 49.25 kB | 49.03 kB |
+| Widget terminal (base + draw + indicators + widget) | 207.75 kB | 207.13 kB |
 | Workspace tier | 6 kB | 5.52 kB |
-| **Everything** | 245 kB | 243.96 kB |
+| **Everything** | 247.25 kB | 246.52 kB |
 
 ## Documentation
 
@@ -500,8 +503,8 @@ See [Contributing](./CONTRIBUTING.md) for setup, targeted checks, documentation
 ```bash
 npm install        # install dev toolchain
 npm run typecheck  # strict TypeScript check
-npm test           # engine unit tests (Vitest): 5734 across 242 files
-npm run test:demo  # reference-host tests: 389 across 30 files
+npm test           # engine unit tests (Vitest): 5841 across 246 files
+npm run test:demo  # reference-host tests: 401 across 31 files
 npm run test:endurance # node endurance-harness tests: 7 cases
 npm run build      # Rollup -> dist/ (minified ESM per tier + types)
 npm run size       # size-limit (Brotli) against the budget
@@ -519,7 +522,7 @@ npm run verify     # lint + types + unit + endurance harness + build + demo + dt
 
 ## Status &amp; limitations
 
-Version **2.4.5**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
+Version **2.4.7**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
 
 Known gaps, stated plainly:
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { TradingCapabilitySource as TradingCapabilitySource$1 } from 'openalgo-charts';
 
 /** Library version string. Matches package.json (including locally prepared releases). */
-declare const VERSION = "2.4.5";
+declare const VERSION = "2.4.7";
 /** Returns the current library version. */
 declare function version(): string;
 
@@ -812,6 +812,8 @@ interface PrimitiveHit {
      * declares it here, and the drag callbacks receive time as well as price.
      */
     draggable?: boolean;
+    /** Opt into Escape cancellation without a release. Listen for `drag:cancel` to discard the preview. */
+    cancelOnEscape?: boolean;
 }
 /** Injected when a primitive is attached; lets it request a repaint. */
 interface PrimitiveHost {
@@ -859,6 +861,11 @@ interface IPrimitive {
 /** Pick the best hit across primitives: nearest distance, then z-order priority. */
 declare function bestHit(hits: readonly (PrimitiveHit | null)[]): PrimitiveHit | null;
 
+/**
+ * Series markers (ARCHITECTURE.md §8.1): buy/sell signals and shapes anchored
+ * to bars. Visible-range culled, per-bar stacked, four discrete sizes.
+ */
+
 /**
  * `labelUp` / `labelDown` are text plates with a tail, for named signals ("Buy",
  * "Sell") rather than bare glyphs. The tail points *at* the anchor price and the
@@ -900,10 +907,23 @@ declare function drawShape(ctx: CanvasRenderingContext2D, shape: MarkerShape, cx
 declare function drawLabel(ctx: CanvasRenderingContext2D, up: boolean, cx: number, anchorY: number, text: string, color: string, fontPx: number): void;
 declare class SeriesMarkers implements IPrimitive {
     private readonly _seriesId;
+    private readonly _fallbackBars;
+    private readonly _priceScale;
     private _markers;
     private _host;
     private _lastPositions;
-    constructor(seriesId: SeriesId);
+    /**
+     * @param seriesId The series whose pane and price scale the marks live on.
+     * @param fallbackBars Bars to position against where that series has none.
+     *
+     * The second argument exists because a marker's series decides *where* it is
+     * drawn while the bar under it decides *how high*, and those are not always
+     * the same row of data. An indicator that draws one line in an uptrend and
+     * another in a downtrend has a gap in each, and a mark that lands in a gap
+     * had no bar to measure from and was dropped without a word. The caller
+     * passes the instrument's own bars, which have no gaps.
+     */
+    constructor(seriesId: SeriesId, fallbackBars?: () => readonly Bar[], priceScale?: () => PriceScale);
     attached(host: PrimitiveHost): void;
     detached(): void;
     zOrder(): ZOrder;
@@ -975,8 +995,14 @@ interface SeriesApi {
     remove(): void;
     /** The price scale this series maps to (call `.setOptions({ marginTop, marginBottom })` on it). */
     priceScale(): PriceScale;
-    /** Create a markers layer (buy/sell signals, shapes) bound to this series. */
-    createMarkers(): SeriesMarkers;
+    /**
+     * Create a markers layer (buy/sell signals, shapes) bound to this series.
+     *
+     * `fallbackBars` positions a mark whose time this series has no point for,
+     * which happens whenever the series is drawn with gaps. Without it such a
+     * mark is dropped silently.
+     */
+    createMarkers(fallbackBars?: () => readonly Bar[]): SeriesMarkers;
 }
 
 /**
@@ -1679,7 +1705,7 @@ declare class PriceLine implements IPrimitive {
  * placeholder.
  */
 
-type PaneLegendAction = 'hide' | 'settings' | 'up' | 'down' | 'maximize' | 'close';
+type PaneLegendAction = 'hide' | 'settings' | 'source' | 'up' | 'down' | 'maximize' | 'close';
 /**
  * One reading on a legend row. Multi-plot sources show one per plot, each in
  * that plot's own color (an MA ribbon's four averages, MACD's three lines) —
@@ -1796,6 +1822,7 @@ interface PaneLegendOptions {
      * `${id}::<action>`:
      *  - `up` / `down` — move this pane one slot (`::up` / `::down`)
      *  - `hide`        — toggle visibility (`::hide`)
+     *  - `source`: show the code this source was written from (`::source`)
      *  - `maximize`    — expand this pane to fill the chart (`::maximize`)
      *  - `close`       — remove the source, and its pane if it empties (`::close`)
      *
@@ -1810,6 +1837,15 @@ interface PaneLegendOptions {
     maximized?: boolean;
     /** Text size in media px. Default 11. */
     font?: number;
+    /**
+     * Square side of one action button in media px. Default 16.
+     *
+     * The row grows to hold it, so raising this moves every legend row below it
+     * down by the same amount and nothing overlaps. It is a chart-wide setting
+     * for that reason: two legends on one pane with different button sizes would
+     * stack against different row heights and collide.
+     */
+    iconSize?: number;
     /** Left inset from the plot edge in media px. Default 8. */
     left?: number;
     /** Top inset in media px. Default 6. */
@@ -2018,10 +2054,14 @@ interface IndicatorHost {
         color?: string;
         row: number;
         paneIndex: number;
+        /** The descriptor's `hasSource`, so the row can offer a source button. */
+        hasSource?: boolean;
     }): PaneLegend;
     removeIndicatorLegend(legend: PaneLegend): void;
     /** How many legends already sit on this pane, so rows stack. */
     legendRowsOn(paneIndex: number): number;
+    /** The instrument's own series, for a descriptor anchoring marks to price. */
+    primarySeries?(): SeriesApi | null;
     addIndicatorSeries(type: string, paneIndex: number, style: Record<string, unknown> | undefined, priceScaleId: string | undefined, 
     /** Axis/crosshair formatting for the scale this plot maps to. */
     priceFormat?: PriceFormat): SeriesApi;
@@ -2920,6 +2960,20 @@ interface IndicatorDescriptor {
     category?: string;
     /** `'onchart'` overlays the price pane; `'pane'` gets its own pane. */
     placement: 'onchart' | 'pane';
+    /**
+     * This indicator was written from code the host can show the user.
+     *
+     * Its legend row then carries a source button beside the gear, and pressing
+     * it emits `indicatorSource` with the same payload `indicatorSettings`
+     * carries. The engine does not hold the code and does not want to: a
+     * descriptor may be compiled from a script, generated, or written by hand in
+     * the host's own bundle, and only the host knows which of those it can put in
+     * front of somebody. So this says a button is worth offering, and the host
+     * decides what the button opens.
+     *
+     * Absent or false draws no button, which is every built-in study.
+     */
+    hasSource?: boolean;
     inputs: readonly IndicatorInput[];
     plots: readonly IndicatorPlot[];
     /**
@@ -2973,6 +3027,24 @@ interface IndicatorDescriptor {
         values: IndicatorValues;
         settings: Readonly<IndicatorSettings>;
     }): readonly SeriesMarker[];
+    /**
+     * What `aboveBar` and `belowBar` are measured against.
+     *
+     * `'plot'`, the default, is this study's own first plot, which is right for a
+     * mark that belongs to the line: an arrow on a moving average sits against
+     * the average.
+     *
+     * `'price'` is the instrument's candles, so above is above the high and below
+     * is below the low. That is what a buy or sell signal on an overlay study
+     * means, and anchoring one to the study's own column instead puts it wherever
+     * that column happens to sit: a study that anchors its marks to a mid-body
+     * line draws every "below" mark through the middle of the candle.
+     *
+     * Ignored by a study in its own pane, which has no candles to measure
+     * against, and ignored when the chart has no primary series yet. Both fall
+     * back to the first plot rather than dropping the marker.
+     */
+    markerAnchor?: 'plot' | 'price';
     /**
      * Optional summary grid pinned to a corner of the pane.
      *
@@ -4112,6 +4184,11 @@ interface ChartOptions {
     canvas?: CanvasOptions;
     /** Per-field status-line switches applied to every pane legend on the chart. */
     statusLine?: LegendStatusLineOptions;
+    /**
+     * Square side of a legend action button in media px. Default 16, held to
+     * 12..28. Applied to every pane legend, because the rows stack against it.
+     */
+    legendIconSize?: number;
     /** Accessible label for the chart container (screen readers). */
     ariaLabel?: string;
     /**
@@ -4264,7 +4341,7 @@ interface PointerSample {
 }
 /**
  * What the engine reports about the physical pointer behind a gesture.
- * `crosshair:move`, `click`, `drag` and `drag:end` all carry these keys.
+ * `crosshair:move`, `click`, `drag:start`, `drag` and `drag:end` all carry these keys.
  */
 interface PointerInfo {
     modifiers: PointerModifiers;
@@ -4318,7 +4395,7 @@ interface ChartDragEvent extends PointerInfo {
      */
     samples: PointerSample[];
 }
-/** Payload of the `drag:end` event: the release that finished a primitive drag. */
+/** Payload of `drag:start` (press) and `drag:end` (release) for a primitive drag. */
 interface ChartDragEndEvent extends PointerInfo {
     id: string;
     price: number;
@@ -4458,6 +4535,8 @@ declare class Chart {
     private readonly _canvas;
     /** Status-line switches pushed onto every pane legend, host-added ones included. */
     private readonly _statusLine;
+    /** Legend action-button side in media px; undefined leaves the primitive's default. */
+    private _legendIconSize;
     /** Axis-strip chrome switches. Empty is the shipped chart: neither drawn. */
     private readonly _axisChrome;
     /**
@@ -4557,6 +4636,7 @@ declare class Chart {
     /** Pressure at the press; a click reports this, since its release always reads 0. */
     private _downPressure;
     private _dragId;
+    private _dragCancelOnEscape;
     private _hoverId;
     /** Whether that primitive draws below the overlay, so leaving it must repaint the base. */
     private _hoverOnBase;
@@ -5012,6 +5092,16 @@ declare class Chart {
      */
     setStatusLineOptions(patch: LegendStatusLineOptions): void;
     statusLineOptions(): LegendStatusLineOptions;
+    /**
+     * How large a legend's action buttons are drawn, in media px.
+     *
+     * Chart-wide rather than per legend: the rows stack against the height the
+     * buttons need, so two sizes on one pane would stack against two different
+     * heights and overlap. The primitive holds it to a range it can actually
+     * draw.
+     */
+    setLegendIconSize(size: number): void;
+    legendIconSize(): number | undefined;
     /**
      * Turn the axis-strip chrome on or off, and hand it a clock. Merges field by
      * field, so switching the countdown on leaves the corner clock alone.
@@ -5151,6 +5241,7 @@ declare class Chart {
         grid?: Partial<GridOptions>;
         canvas?: CanvasOptions;
         statusLine?: LegendStatusLineOptions;
+        legendIconSize?: number;
         priceScale?: Partial<PriceScaleOptions>;
         priceFormatter?: ((price: number) => string) | null;
         timeFormatter?: ((utcSeconds: number, tickMark?: TickMarkType) => string) | undefined;
@@ -5418,6 +5509,7 @@ declare class Chart {
     private readonly _onDblClick;
     private _beginPinch;
     private _updatePinch;
+    private _cancelPrimitiveDrag;
     private readonly _onKeyDown;
     /** Scope gating: hover keeps keys chart-local; global always acts. */
     private _shortcutsActive;
@@ -9491,7 +9583,14 @@ declare class AlertController {
     private _replay;
     private _destroyed;
     private _revision;
+    private _drag;
     constructor(_chart: AlertChartHost, options?: AlertControllerOptions);
+    private _dragAvailability;
+    private _dragPrice;
+    private _startDrag;
+    private _cancelDrag;
+    /** Market evaluation keeps the committed source until a moved, owned gesture ends. */
+    private _onDrag;
     add(input: AlertInput): Alert;
     update(id: string, patch: AlertPatch): Alert | undefined;
     remove(id: string): boolean;