hyperprop-charting-library 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -15
- package/docs/AI_CONTEXT.md +60 -0
- package/docs/API.md +198 -0
- package/docs/BRACKETS.md +132 -0
- package/docs/EVENTS.md +89 -0
- package/docs/RECIPES.md +118 -0
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
# hyperprop-charting-library
|
|
2
2
|
|
|
3
|
-
Lightweight TypeScript charting library
|
|
3
|
+
Lightweight TypeScript charting library (Canvas 2D) focused on:
|
|
4
|
+
|
|
5
|
+
- OHLC candlestick rendering
|
|
6
|
+
- pan and zoom interactions
|
|
7
|
+
- price lines and order lines
|
|
8
|
+
- trading-style widgets and callbacks
|
|
9
|
+
- framework-agnostic integration
|
|
4
10
|
|
|
5
11
|
## Install
|
|
6
12
|
|
|
@@ -8,21 +14,15 @@ Lightweight TypeScript charting library with Canvas rendering, OHLC candles, axe
|
|
|
8
14
|
npm install hyperprop-charting-library
|
|
9
15
|
```
|
|
10
16
|
|
|
11
|
-
## Quick
|
|
17
|
+
## Quick Start
|
|
12
18
|
|
|
13
19
|
```ts
|
|
14
20
|
import { createChart, type OhlcDataPoint } from "hyperprop-charting-library";
|
|
15
21
|
|
|
16
|
-
const
|
|
17
|
-
if (!
|
|
22
|
+
const root = document.getElementById("chart");
|
|
23
|
+
if (!root) throw new Error("Missing chart container");
|
|
18
24
|
|
|
19
|
-
const chart = createChart(
|
|
20
|
-
width: 900,
|
|
21
|
-
height: 520,
|
|
22
|
-
backgroundColor: "#101114",
|
|
23
|
-
upColor: "#2fb171",
|
|
24
|
-
downColor: "#d35a5a"
|
|
25
|
-
});
|
|
25
|
+
const chart = createChart(root, { width: 900, height: 520 });
|
|
26
26
|
|
|
27
27
|
const data: OhlcDataPoint[] = [
|
|
28
28
|
{ t: "2026-01-01T00:00:00.000Z", o: 100, h: 104, l: 98, c: 102 },
|
|
@@ -32,7 +32,15 @@ const data: OhlcDataPoint[] = [
|
|
|
32
32
|
chart.setData(data);
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
##
|
|
35
|
+
## Full Documentation
|
|
36
|
+
|
|
37
|
+
- API reference: `docs/API.md`
|
|
38
|
+
- Event contracts: `docs/EVENTS.md`
|
|
39
|
+
- Integration recipes: `docs/RECIPES.md`
|
|
40
|
+
- Bracket orders (TP/SL lifecycle): `docs/BRACKETS.md`
|
|
41
|
+
- AI integration context: `docs/AI_CONTEXT.md`
|
|
42
|
+
|
|
43
|
+
## Core API Surface
|
|
36
44
|
|
|
37
45
|
- `createChart(element, options)`
|
|
38
46
|
- `chart.setData(data)`
|
|
@@ -42,7 +50,7 @@ chart.setData(data);
|
|
|
42
50
|
- `chart.setDoubleClickEnabled(enabled)` / `chart.setDoubleClickAction(action)`
|
|
43
51
|
- `chart.resize(width, height)` / `chart.destroy()`
|
|
44
52
|
|
|
45
|
-
##
|
|
53
|
+
## Scope
|
|
46
54
|
|
|
47
|
-
-
|
|
48
|
-
- Playground/demo UI is not part of the
|
|
55
|
+
- This package is chart rendering + chart interaction only.
|
|
56
|
+
- Playground/demo UI is not part of the runtime API.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# AI Integration Context
|
|
2
|
+
|
|
3
|
+
Use this file as context for coding assistants integrating `hyperprop-charting-library`.
|
|
4
|
+
|
|
5
|
+
## What this library is
|
|
6
|
+
|
|
7
|
+
- Canvas-based chart rendering and interaction engine.
|
|
8
|
+
- Framework-agnostic (no React/Vue dependency).
|
|
9
|
+
- Strong support for price lines, order lines, and trading-style widgets.
|
|
10
|
+
|
|
11
|
+
## What this library is not
|
|
12
|
+
|
|
13
|
+
- Not an order execution engine.
|
|
14
|
+
- Not a broker/exchange API.
|
|
15
|
+
- No persistence/state backend.
|
|
16
|
+
|
|
17
|
+
All business rules (order lifecycle, fills, validation, permissions) must be handled in app code.
|
|
18
|
+
|
|
19
|
+
## Integration model
|
|
20
|
+
|
|
21
|
+
1. App owns source-of-truth state.
|
|
22
|
+
2. App translates state -> `setData`, `setPriceLines`, `setOrderLines`.
|
|
23
|
+
3. App listens to `onOrderAction`/`onChartClick`.
|
|
24
|
+
4. App mutates state.
|
|
25
|
+
5. App re-renders lines/data into chart.
|
|
26
|
+
|
|
27
|
+
This pattern is required for reliable drag/update behavior during live ticks.
|
|
28
|
+
|
|
29
|
+
## Canonical event handling
|
|
30
|
+
|
|
31
|
+
- `move` -> update stored price immediately.
|
|
32
|
+
- custom action (for example `execute`) -> run domain logic in app.
|
|
33
|
+
- `dragging: true` -> interim updates during drag.
|
|
34
|
+
- `dragging: false` -> drag completed.
|
|
35
|
+
|
|
36
|
+
## Common mistakes to avoid
|
|
37
|
+
|
|
38
|
+
- Treating chart line visuals as source-of-truth.
|
|
39
|
+
- Putting broker logic inside chart callbacks directly.
|
|
40
|
+
- Ignoring interim drag events while streaming data.
|
|
41
|
+
- Assuming `action` is closed enum. It is open (`string`) by design.
|
|
42
|
+
|
|
43
|
+
## Useful option groups
|
|
44
|
+
|
|
45
|
+
- Display: `backgroundColor`, `axis`, `grid`, `watermark`, `crosshair`, `tickerLine`
|
|
46
|
+
- Candles: `candleBodyWidthRatio`, `candleMinWidth`, `candleWickWidth`
|
|
47
|
+
- Stability: `autoScaleSmoothing`, `autoScaleIgnoreLatestCandle`
|
|
48
|
+
- Interaction: `doubleClickEnabled`, `doubleClickAction`
|
|
49
|
+
- Overlays: `priceLines`, `orderLines`
|
|
50
|
+
|
|
51
|
+
## Suggested docs for AI prompts
|
|
52
|
+
|
|
53
|
+
When using this library in another repo, include:
|
|
54
|
+
|
|
55
|
+
1. `docs/API.md`
|
|
56
|
+
2. `docs/EVENTS.md`
|
|
57
|
+
3. `docs/BRACKETS.md` (if trading/order workflows)
|
|
58
|
+
4. this file (`AI_CONTEXT.md`)
|
|
59
|
+
|
|
60
|
+
That gives enough context for most integration tasks without reading source.
|
package/docs/API.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# API Reference
|
|
2
|
+
|
|
3
|
+
## Main Entry
|
|
4
|
+
|
|
5
|
+
- `createChart(element: HTMLElement, options?: ChartOptions): ChartInstance`
|
|
6
|
+
|
|
7
|
+
Creates and mounts a chart canvas into `element`.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Types
|
|
12
|
+
|
|
13
|
+
### `OhlcDataPoint`
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
type OhlcDataPoint = {
|
|
17
|
+
t: string; // ISO time
|
|
18
|
+
o: number;
|
|
19
|
+
h: number;
|
|
20
|
+
l: number;
|
|
21
|
+
c: number;
|
|
22
|
+
v?: number;
|
|
23
|
+
};
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### `ChartOptions`
|
|
27
|
+
|
|
28
|
+
Top-level options:
|
|
29
|
+
|
|
30
|
+
- `width` (default `720`)
|
|
31
|
+
- `height` (default `360`)
|
|
32
|
+
- `backgroundColor` (default `#ffffff`)
|
|
33
|
+
- `axisColor` (legacy shorthand for axis line/text color)
|
|
34
|
+
- `axis?: AxisOptions`
|
|
35
|
+
- `upColor` (default `#16a34a`)
|
|
36
|
+
- `downColor` (default `#dc2626`)
|
|
37
|
+
- `gridColor` (default `#e2e8f0`)
|
|
38
|
+
- `fontFamily`
|
|
39
|
+
- `candleBodyWidthRatio` (default `0.7`)
|
|
40
|
+
- `candleMinWidth` (default `0.5`)
|
|
41
|
+
- `candleWickWidth` (default `1`)
|
|
42
|
+
- `autoScaleSmoothing` (default `0.16`)
|
|
43
|
+
- `autoScaleIgnoreLatestCandle` (default `true`)
|
|
44
|
+
- `doubleClickEnabled` (default `true`)
|
|
45
|
+
- `doubleClickAction` (`"reset"` | `"placeLimitOrder"`, default `"reset"`)
|
|
46
|
+
- `crosshair?: CrosshairOptions`
|
|
47
|
+
- `grid?: GridOptions`
|
|
48
|
+
- `watermark?: WatermarkOptions`
|
|
49
|
+
- `priceLines?: PriceLineOptions[]`
|
|
50
|
+
- `orderLines?: OrderLineOptions[]`
|
|
51
|
+
- `tickerLine?: TickerLineOptions`
|
|
52
|
+
|
|
53
|
+
### `AxisOptions`
|
|
54
|
+
|
|
55
|
+
- `lineColor` (default `#94a3b8`)
|
|
56
|
+
- `textColor` (default `#94a3b8`)
|
|
57
|
+
- `fontSize` (default `12`)
|
|
58
|
+
- `lineWidth` (default `1`)
|
|
59
|
+
|
|
60
|
+
### `GridOptions`
|
|
61
|
+
|
|
62
|
+
- `color` (default `#e2e8f0`)
|
|
63
|
+
- `opacity` (default `0.9`)
|
|
64
|
+
- `horizontalLines` (default `true`)
|
|
65
|
+
- `verticalLines` (default `true`)
|
|
66
|
+
- `horizontalTickCount` (default `5`)
|
|
67
|
+
|
|
68
|
+
### `CrosshairOptions`
|
|
69
|
+
|
|
70
|
+
- `visible` (default `true`)
|
|
71
|
+
- `color` (default `#94a3b8`)
|
|
72
|
+
- `width` (default `1`)
|
|
73
|
+
- `style` (`"solid" | "dotted" | "dashed"`, default `"dotted"`)
|
|
74
|
+
- `showHorizontal` (default `true`)
|
|
75
|
+
- `showVertical` (default `true`)
|
|
76
|
+
|
|
77
|
+
### `WatermarkOptions`
|
|
78
|
+
|
|
79
|
+
- `visible` (default `false`)
|
|
80
|
+
- `text` (default `""`)
|
|
81
|
+
- `color` (default `#94a3b8`)
|
|
82
|
+
- `opacity` (default `0.2`)
|
|
83
|
+
- `fontSize` (default `92`)
|
|
84
|
+
- `fontWeight` (default `700`)
|
|
85
|
+
- `thickness` (stroke width, default `0`)
|
|
86
|
+
|
|
87
|
+
### `TickerLineOptions`
|
|
88
|
+
|
|
89
|
+
- `visible` (default `true`)
|
|
90
|
+
- `style` (`"solid" | "dotted" | "dashed"`, default `"dashed"`)
|
|
91
|
+
- `thickness` (default `1`)
|
|
92
|
+
- `color` (default `#22c55e`)
|
|
93
|
+
- `labelBackgroundColor` (default `#22c55e`)
|
|
94
|
+
- `labelTextColor` (default `#0b1220`)
|
|
95
|
+
- `labelBorderRadius` (default `6`)
|
|
96
|
+
|
|
97
|
+
### `PriceLineOptions`
|
|
98
|
+
|
|
99
|
+
- `id?: string`
|
|
100
|
+
- `price: number` (required)
|
|
101
|
+
- `label?: string`
|
|
102
|
+
- `visible` (default `true`)
|
|
103
|
+
- `style` (`"solid" | "dotted" | "dashed"`, default `"solid"`)
|
|
104
|
+
- `thickness` (default `1`)
|
|
105
|
+
- `color` (default `#f59e0b`)
|
|
106
|
+
- `labelBackgroundColor` (default `#f59e0b`)
|
|
107
|
+
- `labelTextColor` (default `#0f172a`)
|
|
108
|
+
- `labelBorderRadius` (default `3`)
|
|
109
|
+
- `showLabel` (default `true`)
|
|
110
|
+
|
|
111
|
+
### `OrderActionButton`
|
|
112
|
+
|
|
113
|
+
- `text: string` (required)
|
|
114
|
+
- `action: string` (required)
|
|
115
|
+
- `draggable?: boolean`
|
|
116
|
+
- `textColor?: string`
|
|
117
|
+
- `backgroundColor?: string`
|
|
118
|
+
- `borderColor?: string`
|
|
119
|
+
- `borderStyle?: "solid" | "dotted" | "dashed"`
|
|
120
|
+
- `borderRadius?: number`
|
|
121
|
+
- `minWidth?: number`
|
|
122
|
+
- `paddingX?: number`
|
|
123
|
+
- `fullHeight?: boolean`
|
|
124
|
+
- `fontWeight?: number | string`
|
|
125
|
+
|
|
126
|
+
### `OrderLineOptions`
|
|
127
|
+
|
|
128
|
+
Required fields:
|
|
129
|
+
|
|
130
|
+
- `type: "market" | "limit" | "stop" | "takeProfit"`
|
|
131
|
+
- `side: "buy" | "sell"`
|
|
132
|
+
- `price: number`
|
|
133
|
+
|
|
134
|
+
Common optional fields:
|
|
135
|
+
|
|
136
|
+
- `id?: string`
|
|
137
|
+
- `behavior?: "static" | "follow"` (default `"static"`)
|
|
138
|
+
- `followPrice?: number`
|
|
139
|
+
- `qty?: number`
|
|
140
|
+
- `pnl?: number`
|
|
141
|
+
- `label?: string`
|
|
142
|
+
- `visible?: boolean` (default `true`)
|
|
143
|
+
- `style?: "solid" | "dotted" | "dashed"` (default `"solid"`)
|
|
144
|
+
- `thickness?: number` (default `1`)
|
|
145
|
+
- `color?: string` (default `#f59e0b`)
|
|
146
|
+
- `labelBackgroundColor?: string`
|
|
147
|
+
- `labelTextColor?: string`
|
|
148
|
+
- `labelBorderRadius?: number` (default `3`)
|
|
149
|
+
- `showCloseButton?: boolean` (default `true`)
|
|
150
|
+
- `widgetPosition?: "left" | "center" | "right"` (default `"left"`)
|
|
151
|
+
- `draggable?: boolean` (default `false`)
|
|
152
|
+
|
|
153
|
+
Legacy single action button:
|
|
154
|
+
|
|
155
|
+
- `actionButtonText?: string`
|
|
156
|
+
- `actionButtonAction?: string` (default `"execute"`)
|
|
157
|
+
- `actionButtonTextColor?: string`
|
|
158
|
+
- `actionButtonBackgroundColor?: string`
|
|
159
|
+
- `actionButtonBorderRadius?: number`
|
|
160
|
+
- `actionButtonMinWidth?: number`
|
|
161
|
+
- `actionButtonPaddingX?: number`
|
|
162
|
+
- `actionButtonFullHeight?: boolean`
|
|
163
|
+
- `actionButtonFontWeight?: number | string`
|
|
164
|
+
- `actionButtonBorderColor?: string`
|
|
165
|
+
- `actionButtonBorderStyle?: "solid" | "dotted" | "dashed"`
|
|
166
|
+
|
|
167
|
+
Multi-button actions:
|
|
168
|
+
|
|
169
|
+
- `actionButtons?: OrderActionButton[]` (default `[]`)
|
|
170
|
+
|
|
171
|
+
Connector/fill visuals:
|
|
172
|
+
|
|
173
|
+
- `connectorToPrice?: number`
|
|
174
|
+
- `connectorColor?: string`
|
|
175
|
+
- `connectorStyle?: "solid" | "dotted" | "dashed"` (default `"dotted"`)
|
|
176
|
+
- `connectorThickness?: number` (default `1`)
|
|
177
|
+
- `connectorAnchorPaddingRight?: number` (default `10`)
|
|
178
|
+
- `fillToPrice?: number`
|
|
179
|
+
- `fillColor?: string`
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## `ChartInstance` Methods
|
|
184
|
+
|
|
185
|
+
- `setData(data: OhlcDataPoint[]): void`
|
|
186
|
+
- `setPriceLines(lines: PriceLineOptions[]): void`
|
|
187
|
+
- `addPriceLine(line: PriceLineOptions): string`
|
|
188
|
+
- `removePriceLine(id: string): void`
|
|
189
|
+
- `setOrderLines(lines: OrderLineOptions[]): void`
|
|
190
|
+
- `addOrderLine(line: OrderLineOptions): string`
|
|
191
|
+
- `updateOrderLine(id: string, patch: Partial<OrderLineOptions>): void`
|
|
192
|
+
- `removeOrderLine(id: string): void`
|
|
193
|
+
- `onOrderAction(handler: ((event: OrderActionEvent) => void) | null): void`
|
|
194
|
+
- `onChartClick(handler: ((event: ChartClickEvent) => void) | null): void`
|
|
195
|
+
- `setDoubleClickEnabled(enabled: boolean): void`
|
|
196
|
+
- `setDoubleClickAction(action: "reset" | "placeLimitOrder"): void`
|
|
197
|
+
- `resize(width?: number, height?: number): void`
|
|
198
|
+
- `destroy(): void`
|
package/docs/BRACKETS.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Bracket Orders (TP/SL) Integration
|
|
2
|
+
|
|
3
|
+
This library provides chart primitives and interaction events.
|
|
4
|
+
Bracket behavior (preview, pending, activation, OCO) is implemented in app state.
|
|
5
|
+
|
|
6
|
+
Use this guide as the canonical flow.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Conceptual Model
|
|
11
|
+
|
|
12
|
+
Keep 3 layers in your app:
|
|
13
|
+
|
|
14
|
+
1. **Preview layer** (before placement)
|
|
15
|
+
- `previewLimitPrice`
|
|
16
|
+
- `previewTpPrice`
|
|
17
|
+
- `previewSlPrice`
|
|
18
|
+
2. **Pending bracket layer** (entry not filled yet)
|
|
19
|
+
- keyed by `entryOrderId`
|
|
20
|
+
- stores pending TP/SL values
|
|
21
|
+
3. **Active order layer** (entry filled)
|
|
22
|
+
- active `market` position line
|
|
23
|
+
- active TP/SL exit lines
|
|
24
|
+
|
|
25
|
+
The chart only renders what you feed via `setOrderLines(...)`.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Recommended Flow
|
|
30
|
+
|
|
31
|
+
### 1) Create preview limit
|
|
32
|
+
|
|
33
|
+
- From click/double-click in plot, set `previewLimitPrice`.
|
|
34
|
+
- Render preview order line with custom buttons:
|
|
35
|
+
- `Buy/Sell` (`action: "execute"`)
|
|
36
|
+
- `TP` (`action: "previewTp"`, `draggable: true`)
|
|
37
|
+
- `SL` (`action: "previewSl"`, `draggable: true`)
|
|
38
|
+
|
|
39
|
+
### 2) Set preview TP/SL
|
|
40
|
+
|
|
41
|
+
- On `onOrderAction`:
|
|
42
|
+
- `action === "previewTp"` -> set/update `previewTpPrice`
|
|
43
|
+
- `action === "previewSl"` -> set/update `previewSlPrice`
|
|
44
|
+
- Use `event.dragging`:
|
|
45
|
+
- `true`: live drag updates
|
|
46
|
+
- `false`: drag end
|
|
47
|
+
|
|
48
|
+
### 3) Validate side rules before execute
|
|
49
|
+
|
|
50
|
+
- Buy entry:
|
|
51
|
+
- TP must be `>` limit
|
|
52
|
+
- SL must be `<` limit
|
|
53
|
+
- Sell entry:
|
|
54
|
+
- TP must be `<` limit
|
|
55
|
+
- SL must be `>` limit
|
|
56
|
+
|
|
57
|
+
If invalid, disable execute action in your state/UI.
|
|
58
|
+
|
|
59
|
+
### 4) Execute preview
|
|
60
|
+
|
|
61
|
+
On `action === "execute"`:
|
|
62
|
+
|
|
63
|
+
- Create entry limit order.
|
|
64
|
+
- If TP/SL exists, store them as **pending brackets** tied to `entryOrderId`.
|
|
65
|
+
- Clear preview state.
|
|
66
|
+
|
|
67
|
+
### 5) Convert pending to active on fill
|
|
68
|
+
|
|
69
|
+
When your fill logic marks entry as filled:
|
|
70
|
+
|
|
71
|
+
- Transition entry line to active position line (for example `market` + `follow` behavior).
|
|
72
|
+
- Create active TP/SL lines from pending bracket values.
|
|
73
|
+
- Remove pending bracket object.
|
|
74
|
+
|
|
75
|
+
### 6) OCO behavior
|
|
76
|
+
|
|
77
|
+
If active TP or SL fills:
|
|
78
|
+
|
|
79
|
+
- Close/transition position as needed.
|
|
80
|
+
- Remove the sibling exit leg (OCO cleanup).
|
|
81
|
+
|
|
82
|
+
### 7) Position close behavior
|
|
83
|
+
|
|
84
|
+
If user closes active position manually:
|
|
85
|
+
|
|
86
|
+
- Remove linked active TP/SL lines too.
|
|
87
|
+
- Remove any pending bracket bound to that entry id.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Useful `OrderLineOptions` for Brackets
|
|
92
|
+
|
|
93
|
+
- `actionButtons` (custom Buy/TP/SL controls)
|
|
94
|
+
- `draggable` (line dragging)
|
|
95
|
+
- `connectorToPrice` + `connectorStyle` + `connectorAnchorPaddingRight`
|
|
96
|
+
- `fillToPrice` + `fillColor` (drag preview zone)
|
|
97
|
+
- `widgetPosition`
|
|
98
|
+
- `label`, `qty`, `pnl`
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Event Contract Essentials
|
|
103
|
+
|
|
104
|
+
From `onOrderAction(event)`:
|
|
105
|
+
|
|
106
|
+
- `event.action`: open string for app-defined workflows
|
|
107
|
+
- `event.price`: provided for move/drag contexts
|
|
108
|
+
- `event.dragging`: streaming drag state (`true` while dragging, `false` on release)
|
|
109
|
+
- `event.orderId`: line identity to map back to app state
|
|
110
|
+
|
|
111
|
+
Use ids as your state join key.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Minimal State Skeleton
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
type PreviewState = {
|
|
119
|
+
side: "buy" | "sell";
|
|
120
|
+
limit: number | null;
|
|
121
|
+
tp: number | null;
|
|
122
|
+
sl: number | null;
|
|
123
|
+
};
|
|
124
|
+
|
|
125
|
+
type PendingBracket = {
|
|
126
|
+
entryOrderId: string;
|
|
127
|
+
tpPrice: number | null;
|
|
128
|
+
slPrice: number | null;
|
|
129
|
+
};
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Keep this state in your app and regenerate chart lines from it each render/update tick.
|
package/docs/EVENTS.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Events
|
|
2
|
+
|
|
3
|
+
## `onOrderAction`
|
|
4
|
+
|
|
5
|
+
Register:
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
chart.onOrderAction((event) => {
|
|
9
|
+
// handle
|
|
10
|
+
});
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Payload type:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
type OrderActionEvent = {
|
|
17
|
+
orderId?: string;
|
|
18
|
+
action: "close" | "cancel" | "move" | "createLimit" | "execute" | string;
|
|
19
|
+
price?: number;
|
|
20
|
+
dragging?: boolean;
|
|
21
|
+
line?: OrderLineOptions;
|
|
22
|
+
};
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### Common actions
|
|
26
|
+
|
|
27
|
+
- `execute`: action button pressed (for example Buy/Sell)
|
|
28
|
+
- `close`: close button pressed (usually market-type line)
|
|
29
|
+
- `cancel`: cancel button pressed (usually pending line)
|
|
30
|
+
- `move`: draggable line moved
|
|
31
|
+
- `createLimit`: double-click action in `placeLimitOrder` mode
|
|
32
|
+
|
|
33
|
+
### Drag semantics
|
|
34
|
+
|
|
35
|
+
For draggable actions and lines:
|
|
36
|
+
|
|
37
|
+
- during drag updates: `dragging: true`
|
|
38
|
+
- on drag end: `dragging: false` (final value)
|
|
39
|
+
|
|
40
|
+
For `move`:
|
|
41
|
+
|
|
42
|
+
- `price` contains the new line price.
|
|
43
|
+
|
|
44
|
+
### Notes
|
|
45
|
+
|
|
46
|
+
- `action` is intentionally open (`string`) so app code can define custom actions.
|
|
47
|
+
- `line` is the line snapshot associated with the hit region when available.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## `onChartClick`
|
|
52
|
+
|
|
53
|
+
Register:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
chart.onChartClick((event) => {
|
|
57
|
+
// handle
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Payload type:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
type ChartClickEvent = {
|
|
65
|
+
x: number;
|
|
66
|
+
y: number;
|
|
67
|
+
price?: number;
|
|
68
|
+
region: "plot" | "x-axis" | "y-axis";
|
|
69
|
+
};
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Behavior
|
|
73
|
+
|
|
74
|
+
- `region` tells where the click happened.
|
|
75
|
+
- `price` is provided for `plot` region clicks.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Double-click integration
|
|
80
|
+
|
|
81
|
+
Set behavior:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
chart.setDoubleClickEnabled(true);
|
|
85
|
+
chart.setDoubleClickAction("placeLimitOrder"); // or "reset"
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- `"placeLimitOrder"` emits `onOrderAction({ action: "createLimit", price })` when double-clicking plot.
|
|
89
|
+
- `"reset"` resets viewport/scale behavior.
|
package/docs/RECIPES.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Recipes
|
|
2
|
+
|
|
3
|
+
## Basic chart setup
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { createChart } from "hyperprop-charting-library";
|
|
7
|
+
|
|
8
|
+
const chart = createChart(rootEl, {
|
|
9
|
+
width: 900,
|
|
10
|
+
height: 520,
|
|
11
|
+
backgroundColor: "#101114",
|
|
12
|
+
upColor: "#2fb171",
|
|
13
|
+
downColor: "#d35a5a",
|
|
14
|
+
grid: { opacity: 0.35, horizontalTickCount: 4 }
|
|
15
|
+
});
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Streaming updates
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
chart.setData(nextData);
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Use:
|
|
25
|
+
|
|
26
|
+
- `autoScaleSmoothing` for smoother scale transitions
|
|
27
|
+
- `autoScaleIgnoreLatestCandle` to reduce live-candle jitter
|
|
28
|
+
|
|
29
|
+
## Add a static alert/level line
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
chart.addPriceLine({
|
|
33
|
+
price: 6650,
|
|
34
|
+
label: "Alert",
|
|
35
|
+
style: "dotted",
|
|
36
|
+
color: "#f59e0b",
|
|
37
|
+
showLabel: true
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Add a draggable pending limit line
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
chart.addOrderLine({
|
|
45
|
+
type: "limit",
|
|
46
|
+
side: "buy",
|
|
47
|
+
price: 6480,
|
|
48
|
+
qty: 1,
|
|
49
|
+
draggable: true,
|
|
50
|
+
style: "dotted"
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Handle persistence:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
chart.onOrderAction((event) => {
|
|
58
|
+
if (event.action === "move" && event.price !== undefined) {
|
|
59
|
+
// persist new price in your app state
|
|
60
|
+
}
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Use custom action buttons
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
chart.setOrderLines([
|
|
68
|
+
{
|
|
69
|
+
type: "limit",
|
|
70
|
+
side: "buy",
|
|
71
|
+
price: 6488,
|
|
72
|
+
qty: 1,
|
|
73
|
+
actionButtons: [
|
|
74
|
+
{ text: "Buy", action: "execute", backgroundColor: "#3b82f6" },
|
|
75
|
+
{ text: "TP", action: "previewTp", draggable: true, borderStyle: "dotted" },
|
|
76
|
+
{ text: "SL", action: "previewSl", draggable: true, borderStyle: "dotted" }
|
|
77
|
+
]
|
|
78
|
+
}
|
|
79
|
+
]);
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Draw connector between two prices
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
chart.addOrderLine({
|
|
86
|
+
type: "takeProfit",
|
|
87
|
+
side: "sell",
|
|
88
|
+
price: 6650,
|
|
89
|
+
connectorToPrice: 6488,
|
|
90
|
+
connectorStyle: "dashed",
|
|
91
|
+
connectorAnchorPaddingRight: 34
|
|
92
|
+
});
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Preview fill zone while dragging
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
chart.addOrderLine({
|
|
99
|
+
type: "takeProfit",
|
|
100
|
+
side: "sell",
|
|
101
|
+
price: 6650,
|
|
102
|
+
fillToPrice: 6488,
|
|
103
|
+
fillColor: "rgba(45,212,191,0.16)"
|
|
104
|
+
});
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## One-click + double-click limit placement
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
chart.setDoubleClickEnabled(true);
|
|
111
|
+
chart.setDoubleClickAction("placeLimitOrder");
|
|
112
|
+
|
|
113
|
+
chart.onChartClick((event) => {
|
|
114
|
+
if (event.region === "plot" && event.price !== undefined) {
|
|
115
|
+
// create one-click preview state in your app
|
|
116
|
+
}
|
|
117
|
+
});
|
|
118
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hyperprop-charting-library",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Lightweight TypeScript charting core",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/hyperprop-charting-library.cjs",
|
|
@@ -14,7 +14,9 @@
|
|
|
14
14
|
}
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
|
-
"dist"
|
|
17
|
+
"dist",
|
|
18
|
+
"README.md",
|
|
19
|
+
"docs"
|
|
18
20
|
],
|
|
19
21
|
"scripts": {
|
|
20
22
|
"build": "tsup src/index.ts --format esm,cjs --dts --clean && cp \"./dist/index.js\" \"./dist/hyperprop-charting-library.js\" && cp \"./dist/index.cjs\" \"./dist/hyperprop-charting-library.cjs\" && cp \"./dist/index.d.ts\" \"./dist/hyperprop-charting-library.d.ts\"",
|