openalgo-charts 2.4.8 → 2.5.1

package/README.md

@@ -12,7 +12,7 @@ with no runtime dependencies.
 [![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)
 [![npm downloads](https://img.shields.io/npm/dm/openalgo-charts.svg?color=0ea5e9&label=npm%20downloads)](https://www.npmjs.com/package/openalgo-charts)
-[![tests](https://img.shields.io/badge/engine%20tests-5854%20passing-brightgreen.svg)](#develop)
+[![tests](https://img.shields.io/badge/engine%20tests-5918%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)
@@ -25,7 +25,7 @@ with no runtime dependencies.
 npm install openalgo-charts
 ```
 
-Current version: **2.4.8**. Hold the plot to move it in any direction; release to stop.
+Current version: **2.5.1**. Hosts can hide finished alert lines while keeping their saved history.
 See the [changelog](./CHANGELOG.md) for release notes.
 
 ## Quick start
@@ -56,7 +56,7 @@ for live data, or [the widget example](#the-whole-terminal-in-one-call) for char
 
 ## Architecture
 
-<a href="docs/architecture-diagram.svg"><img src="docs/architecture-diagram.svg" alt="OpenAlgo Charts 2.4.8 architecture: host responsibilities, the base data-to-rendering pipeline with alerts and shared replay, and eight optional tiers including workspace storage, trading tools and the widget" width="920" /></a>
+<a href="docs/architecture-diagram.svg"><img src="docs/architecture-diagram.svg" alt="OpenAlgo Charts 2.5.1 architecture: host responsibilities, the base data-to-rendering pipeline with alerts and shared replay, and eight optional tiers including workspace storage, trading tools and the widget" width="920" /></a>
 
 How data reaches the chart, what your app owns, and which features you can import.
 [Open the full-size diagram](docs/architecture-diagram.svg).
@@ -107,7 +107,7 @@ You can also load the library from a CDN in a plain HTML page:
 ```html
 <div id="chart" style="width:100vw;height:100vh"></div>
 <script type="module">
-  import { createChart, generateBars } from 'https://unpkg.com/openalgo-charts@2.4.8/dist/openalgo-charts.mjs';
+  import { createChart, generateBars } from 'https://unpkg.com/openalgo-charts@2.5.1/dist/openalgo-charts.mjs';
   const chart = createChart(document.getElementById('chart'), { timezone: 'Asia/Kolkata' });
   chart.addSeries('candlestick').setData(generateBars(1700000000, 200, 3600));
   chart.fitContent();
@@ -157,17 +157,17 @@ Unused optional tiers stay out of the base chart download.
 
 | Import | Contents | Brotli |
 |---|---|---|
-| `openalgo-charts` | Engine, 13 chart types, panes and scales, custom indicator registry, primitives, alerts, replay, comparisons, chart linking, state, feeds, bar cache, trading overlays, CSV and SVG export | 92.94 kB |
+| `openalgo-charts` | Engine, 13 chart types, panes and scales, custom indicator registry, primitives, alerts, replay, comparisons, chart linking, state, feeds, bar cache, trading overlays, CSV and SVG export | 93.60 kB |
 | `openalgo-charts/indicators` | 105 built-in indicators, calculation helpers and helpers for studies that use external data | 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 and bracket tools, plus a depth-of-market ladder | 8.01 kB |
 | `openalgo-charts/webgl` | GPU drawing for supported series, with Canvas 2D fallback | 6.39 kB |
-| `openalgo-charts/widget` | `createWidget`: toolbar, drawing controls, dialogs, mobile controls, status line, shortcuts and optional layout persistence | 49.03 kB |
+| `openalgo-charts/widget` | `createWidget`: toolbar, drawing controls, dialogs, mobile controls, status line, shortcuts and optional layout persistence | 49.06 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 **246.63 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 207.24 kB. Figures are measured from the 2.4.8 release build. The trade tier is 8.01 kB on its own; base + trade costs 100.95 kB. Sizes use decimal kB.
+Everything together is **247.32 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 207.93 kB. Figures are measured from the 2.5.1 release build. The trade tier is 8.01 kB on its own; base + trade costs 101.60 kB. Sizes use decimal kB.
 
 ## What's built
 
@@ -489,17 +489,17 @@ Enforced in CI by [`size-limit`](./.size-limit.json). Nothing is excluded, becau
 
 | Bundle | Limit | Actual |
 |---|---|---|
-| Base engine | 93.5 kB | 92.94 kB |
-| Base + trade | 101.5 kB | 100.95 kB |
+| Base engine | 93.75 kB | 93.60 kB |
+| Base + trade | 101.75 kB | 101.60 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 | 49.25 kB | 49.03 kB |
-| Widget terminal (base + draw + indicators + widget) | 207.75 kB | 207.24 kB |
+| Widget tier | 49.25 kB | 49.06 kB |
+| Widget terminal (base + draw + indicators + widget) | 208.25 kB | 207.93 kB |
 | Workspace tier | 6 kB | 5.52 kB |
-| **Everything** | 247.25 kB | 246.63 kB |
+| **Everything** | 247.75 kB | 247.32 kB |
 
 ## Documentation
 
@@ -544,8 +544,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): 5854 across 246 files
-npm run test:demo  # reference-host tests: 401 across 31 files
+npm test           # engine unit tests (Vitest): 5918 across 249 files
+npm run test:demo  # reference-host tests: 415 across 32 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
@@ -563,7 +563,7 @@ npm run verify     # lint + types + unit + endurance harness + build + demo + dt
 
 ## Status &amp; limitations
 
-Version **2.4.8**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
+Version **2.5.1**. 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.8";
+declare const VERSION = "2.5.1";
 /** Returns the current library version. */
 declare function version(): string;
 
@@ -1908,8 +1908,16 @@ interface ChartTableOptions {
     position: TablePosition;
     /** Gap from the pane edge, media px. */
     margin: number;
-    /** Column width in media px. A per-column array sizes each one separately. */
-    cellWidth: number | readonly number[];
+    /**
+     * Column width in media px. A per-column array sizes each one separately.
+     *
+     * `'auto'` measures instead: every column takes the width of its own widest
+     * cell at the size that cell will be drawn at. A grid whose cells are
+     * sentences rather than numbers cannot be sized by a caller who has not
+     * measured the text, and a fixed width there is a column of readings running
+     * into the column beside it.
+     */
+    cellWidth: number | readonly number[] | 'auto';
     cellHeight: number;
     /**
      * Type size in media px, or `'auto'` to fit each cell: as large as its row
@@ -2226,6 +2234,8 @@ interface ChartDataUpdate {
 /** Minimum headless chart surface needed to evaluate alerts. */
 interface AlertChartHost {
     primaryBars(): readonly Bar[];
+    /** Owning price scale for primary-price drag snapping, including a left axis. */
+    primarySeries?(): Pick<SeriesApi, 'priceScale'> | null;
     getDataContext(): Readonly<ChartDataContext> | undefined;
     on(event: string, callback: (payload: unknown) => void): () => void;
     emit(event: string, payload: unknown): void;
@@ -2235,6 +2245,13 @@ interface AlertChartHost {
     removePrimitive?(primitive: IPrimitive): void;
     alertState?(): AlertsDocument | undefined;
     setAlertState?(document: AlertsDocument | undefined): void;
+    /**
+     * A price rounded to the tick the pane's scale is written in.
+     *
+     * Optional, and unrounded is the fallback: a host that declares no tick has
+     * nothing to round to, and inventing one would move a price somebody chose.
+     */
+    snapPrice?(paneIndex: number, price: number): number;
 }
 type AlertCondition = 'crossing' | 'crossingUp' | 'crossingDown' | 'greaterThan' | 'lessThan' | 'enteringRange' | 'leavingRange' | 'matches';
 type AlertPolicy = 'onBarClose' | 'onTouch';
@@ -2304,7 +2321,11 @@ interface BarCondition {
     /** Runs at the alert's chosen policy, never for loaded history. */
     when(context: BarConditionContext): boolean;
 }
-/** An alert belongs to the instrument and interval present when it was armed. */
+/**
+ * Evaluation belongs to the instrument and interval present when the alert was armed.
+ * Fixed price levels remain visible on other intervals of the same instrument,
+ * labelled with their original timeframe and paused until it is displayed again.
+ */
 interface AlertScope {
     symbol?: string;
     exchange?: string;
@@ -2368,6 +2389,23 @@ interface AlertControllerOptions {
     drawings?: AlertDrawingProvider;
     /** PriceLine visuals are enabled on chart hosts; disable for a model-only consumer. */
     visuals?: boolean;
+    /**
+     * Whether a spent alert keeps its line. Defaults to `'show'`.
+     *
+     * A triggered or expired alert is no longer watching anything, and the two
+     * defensible things to do with its line are opposites. Keeping it is this
+     * library's default and is why each lifecycle state has its own badge and
+     * colour: the line says what became of the level, which is worth knowing on a
+     * chart somebody has just come back to.
+     *
+     * `'hide'` is for the host where that reading does not pay. A terminal left
+     * open through a session accumulates levels that will never fire again, and
+     * past a certain number the ones still watching are the hardest to pick out
+     * of them. The alert itself is untouched either way: it stays in `list()`,
+     * keeps its lifecycle state, still refuses to fire twice, and gets its line
+     * back if a host re-arms it. Only the drawing goes.
+     */
+    spentLines?: 'show' | 'hide';
 }
 
 /**
@@ -5284,6 +5322,20 @@ declare class Chart {
      */
     drawingState(): unknown;
     setDrawingState(value: unknown): void;
+    /**
+     * A price rounded to the tick the pane's own axis is written with.
+     *
+     * A dragged alert's price comes from a pointer, and a pixel maps to a price
+     * with a dozen decimals behind it: dropped where the axis reads 1255.90 it
+     * was stored as 1255.8706204379562, a price the instrument cannot trade at
+     * and a number nothing in the interface could show. The scale already knows
+     * the tick, because it is the one the axis is written with, so this is the
+     * chart's answer rather than something every host works out again.
+     *
+     * A scale with no declared tick rounds nothing: there is no tick to round to
+     * and inventing one would move a price somebody chose.
+     */
+    snapPrice(paneIndex: number, price: number): number;
     /** Detached JSON state, also available when no alert controller is attached. */
     alertState(): AlertsDocument | undefined;
     /** Runtime snapshot. JSON safety of opaque payloads is checked when state is read. */
@@ -9573,9 +9625,13 @@ declare function roundToTick(value: number, step: number): number;
 declare class AlertController {
     private readonly _chart;
     private readonly _records;
+    /** The alert whose line the pointer is over, for a key that acts on it. */
+    private _hovered;
     private readonly _off;
     private readonly _now;
     private readonly _drawings;
+    /** Whether a spent alert keeps its line; the host's choice, default 'show'. */
+    private readonly _spentLines;
     private readonly _visuals;
     private _timer;
     private _timerAt;
@@ -9587,6 +9643,14 @@ declare class AlertController {
     private _drag;
     constructor(_chart: AlertChartHost, options?: AlertControllerOptions);
     private _dragAvailability;
+    /**
+     * The alert the pointer is over, or none.
+     *
+     * Offered so a host can bind a key to it. The controller does not bind keys
+     * itself: it owns no input and a chart embedded without the widget shell has
+     * its own idea of what a keystroke means.
+     */
+    hovered(): string | undefined;
     private _dragPrice;
     private _startDrag;
     private _cancelDrag;