react-klinecharts-ui 0.1.0 → 0.3.0
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 +528 -29
- package/dist/chunk-PIFLJKYF.cjs +2512 -0
- package/dist/chunk-PIFLJKYF.cjs.map +1 -0
- package/dist/chunk-U325AHHX.js +2468 -0
- package/dist/chunk-U325AHHX.js.map +1 -0
- package/dist/extensions.cjs +12 -4
- package/dist/extensions.d.cts +22 -1
- package/dist/extensions.d.ts +22 -1
- package/dist/extensions.js +1 -1
- package/dist/index.cjs +1936 -49
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +441 -3
- package/dist/index.d.ts +441 -3
- package/dist/index.js +1815 -31
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-PUULIBFN.js +0 -911
- package/dist/chunk-PUULIBFN.js.map +0 -1
- package/dist/chunk-SLTXNLKN.cjs +0 -932
- package/dist/chunk-SLTXNLKN.cjs.map +0 -1
package/README.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
**react-klinecharts-ui** is a headless React library for building financial trading terminals on top of [klinecharts](https://github.com/liihuu/KLineChart). It provides a state provider, a set of hooks, and overlay templates. No UI components are included — use any UI framework you prefer.
|
|
4
4
|
|
|
5
|
+
**[Live Demo](https://nemezzizz.github.io/react-klinecharts-ui/)**
|
|
6
|
+
|
|
7
|
+
### Acknowledgments
|
|
8
|
+
|
|
9
|
+
Many features in this library — including 11 TradingView-style indicators, 9 drawing overlays, the TA math library, undo/redo, layout manager, and script editor — were ported from the [QUANTIX Extended Edition](https://github.com/dsavenk0/KLineChart-Pro) fork of KLineChart-Pro by [@dsavenk0](https://github.com/dsavenk0). The original fork implements these as a tightly-coupled Vue 3 application; this library re-implements them as headless React hooks following the composable, framework-agnostic architecture.
|
|
10
|
+
|
|
5
11
|
---
|
|
6
12
|
|
|
7
13
|
## Table of Contents
|
|
@@ -27,26 +33,34 @@
|
|
|
27
33
|
- [useScreenshot](#usescreenshot)
|
|
28
34
|
- [useFullscreen](#usefullscreen)
|
|
29
35
|
- [useOrderLines](#useorderlines)
|
|
36
|
+
- [useUndoRedo](#useundoredo)
|
|
37
|
+
- [useLayoutManager](#uselayoutmanager)
|
|
38
|
+
- [useScriptEditor](#usescripteditor)
|
|
39
|
+
- [useWatchlist](#usewatchlist)
|
|
40
|
+
- [useCompare](#usecompare)
|
|
41
|
+
- [useMeasure](#usemeasure)
|
|
42
|
+
- [useAnnotations](#useannotations)
|
|
43
|
+
- [useReplay](#usereplay)
|
|
30
44
|
6. [Utilities](#utilities)
|
|
31
45
|
- [createDataLoader](#createdataloader)
|
|
46
|
+
- [TA (Technical Analysis)](#ta-technical-analysis)
|
|
32
47
|
7. [Data & Constants](#data--constants)
|
|
33
|
-
8. [
|
|
34
|
-
9. [
|
|
35
|
-
10. [
|
|
36
|
-
11. [
|
|
48
|
+
8. [Custom Indicator Templates](#custom-indicator-templates)
|
|
49
|
+
9. [Drawing Overlays](#drawing-overlays)
|
|
50
|
+
10. [Extensions](#extensions)
|
|
51
|
+
11. [State Callbacks](#state-callbacks)
|
|
52
|
+
12. [Full Export List](#full-export-list)
|
|
37
53
|
|
|
38
54
|
---
|
|
39
55
|
|
|
40
56
|
## Installation
|
|
41
57
|
|
|
42
|
-
> **Note:** `react-klinecharts` is not yet published to the npm registry. Install it directly from GitHub:
|
|
43
|
-
|
|
44
58
|
```bash
|
|
45
|
-
npm install react-klinecharts-ui
|
|
59
|
+
npm install react-klinecharts-ui react-klinecharts
|
|
46
60
|
# or with pnpm
|
|
47
|
-
pnpm add react-klinecharts-ui
|
|
61
|
+
pnpm add react-klinecharts-ui react-klinecharts
|
|
48
62
|
# or with yarn
|
|
49
|
-
yarn add react-klinecharts-ui
|
|
63
|
+
yarn add react-klinecharts-ui react-klinecharts
|
|
50
64
|
```
|
|
51
65
|
|
|
52
66
|
---
|
|
@@ -737,6 +751,351 @@ removeOrderLine(id!);
|
|
|
737
751
|
|
|
738
752
|
---
|
|
739
753
|
|
|
754
|
+
### useUndoRedo
|
|
755
|
+
|
|
756
|
+
Undo/redo history for drawing overlays and indicator toggles. Automatically connected to `useDrawingTools` and `useIndicators` via a shared context ref — actions are recorded without manual wiring.
|
|
757
|
+
|
|
758
|
+
**Keyboard shortcuts:** `Ctrl+Z` (undo), `Ctrl+Y` / `Ctrl+Shift+Z` (redo).
|
|
759
|
+
|
|
760
|
+
```typescript
|
|
761
|
+
import { useUndoRedo } from "react-klinecharts-ui";
|
|
762
|
+
|
|
763
|
+
const { canUndo, canRedo, undo, redo, pushAction, clear } = useUndoRedo();
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
#### Return type: `UseUndoRedoReturn`
|
|
767
|
+
|
|
768
|
+
| Property | Type | Description |
|
|
769
|
+
|----------|------|-------------|
|
|
770
|
+
| `canUndo` | `boolean` | Whether there are actions to undo |
|
|
771
|
+
| `canRedo` | `boolean` | Whether there are actions to redo |
|
|
772
|
+
| `undo` | `() => void` | Undo the last action |
|
|
773
|
+
| `redo` | `() => void` | Redo the last undone action |
|
|
774
|
+
| `pushAction` | `(action: UndoRedoAction) => void` | Push a new action onto the undo stack (clears redo) |
|
|
775
|
+
| `clear` | `() => void` | Clear all undo/redo history |
|
|
776
|
+
|
|
777
|
+
#### Action types
|
|
778
|
+
|
|
779
|
+
| Type | Trigger | Undo behaviour | Redo behaviour |
|
|
780
|
+
|------|---------|----------------|----------------|
|
|
781
|
+
| `overlay_added` | User completes a drawing | Removes the overlay | Re-creates the overlay |
|
|
782
|
+
| `overlays_removed` | `removeAllDrawings()` | Restores all removed overlays | Re-removes them |
|
|
783
|
+
| `indicator_toggled` | Add/remove indicator | Reverses the toggle | Re-applies the toggle |
|
|
784
|
+
|
|
785
|
+
#### Cross-hook communication
|
|
786
|
+
|
|
787
|
+
`useUndoRedo` registers a `pushAction` callback on `undoRedoListenerRef` (shared via provider context). When `useDrawingTools` finishes a drawing or `useIndicators` toggles an indicator, they call the ref to record the action — no prop drilling required.
|
|
788
|
+
|
|
789
|
+
---
|
|
790
|
+
|
|
791
|
+
### useLayoutManager
|
|
792
|
+
|
|
793
|
+
Save, load, rename, and delete named chart layouts via `localStorage`. Captures indicators, drawings, symbol, and period. Optional auto-save with 5-second debounce.
|
|
794
|
+
|
|
795
|
+
```typescript
|
|
796
|
+
import { useLayoutManager } from "react-klinecharts-ui";
|
|
797
|
+
|
|
798
|
+
const {
|
|
799
|
+
layouts,
|
|
800
|
+
saveLayout,
|
|
801
|
+
loadLayout,
|
|
802
|
+
deleteLayout,
|
|
803
|
+
renameLayout,
|
|
804
|
+
refreshLayouts,
|
|
805
|
+
autoSaveEnabled,
|
|
806
|
+
setAutoSaveEnabled,
|
|
807
|
+
} = useLayoutManager();
|
|
808
|
+
```
|
|
809
|
+
|
|
810
|
+
#### Return type: `UseLayoutManagerReturn`
|
|
811
|
+
|
|
812
|
+
| Property | Type | Description |
|
|
813
|
+
|----------|------|-------------|
|
|
814
|
+
| `layouts` | `LayoutEntry[]` | List of saved layout entries |
|
|
815
|
+
| `saveLayout` | `(name: string) => string \| null` | Save current chart state; returns layout ID |
|
|
816
|
+
| `loadLayout` | `(id: string) => boolean` | Load and apply a layout by ID |
|
|
817
|
+
| `deleteLayout` | `(id: string) => void` | Delete a layout |
|
|
818
|
+
| `renameLayout` | `(id: string, name: string) => boolean` | Rename a layout |
|
|
819
|
+
| `refreshLayouts` | `() => void` | Refresh the list from localStorage |
|
|
820
|
+
| `autoSaveEnabled` | `boolean` | Whether auto-save is enabled |
|
|
821
|
+
| `setAutoSaveEnabled` | `(enabled: boolean) => void` | Toggle auto-save |
|
|
822
|
+
|
|
823
|
+
#### LayoutEntry
|
|
824
|
+
|
|
825
|
+
```typescript
|
|
826
|
+
interface LayoutEntry {
|
|
827
|
+
id: string;
|
|
828
|
+
name: string;
|
|
829
|
+
symbol: string;
|
|
830
|
+
period: string;
|
|
831
|
+
timestamp: number;
|
|
832
|
+
lastModified: number;
|
|
833
|
+
state: ChartLayoutState;
|
|
834
|
+
}
|
|
835
|
+
```
|
|
836
|
+
|
|
837
|
+
#### ChartLayoutState
|
|
838
|
+
|
|
839
|
+
```typescript
|
|
840
|
+
interface ChartLayoutState {
|
|
841
|
+
version: string;
|
|
842
|
+
meta: { symbol: string; period: string; timestamp: number; lastModified: number };
|
|
843
|
+
indicators: Array<{ paneId: string; name: string; calcParams: any[]; visible: boolean }>;
|
|
844
|
+
drawings: Array<{ name: string; points: any[]; styles?: any; extendData?: any }>;
|
|
845
|
+
}
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
---
|
|
849
|
+
|
|
850
|
+
### useScriptEditor
|
|
851
|
+
|
|
852
|
+
Pine Script-style custom indicator editor. Users write plain JavaScript function bodies that receive `TA`, `dataList` (array of `KLineData`), and `params` (parsed from a comma-separated string). The script must return an array of objects — one per candle, each key becomes a chart series.
|
|
853
|
+
|
|
854
|
+
Scripts execute inside a sandboxed `new Function()` with dangerous globals shadowed: `fetch`, `XMLHttpRequest`, `WebSocket`, `Worker`, `SharedWorker`, `importScripts`, `self`, `caches`, `indexedDB`.
|
|
855
|
+
|
|
856
|
+
```typescript
|
|
857
|
+
import { useScriptEditor } from "react-klinecharts-ui";
|
|
858
|
+
|
|
859
|
+
const {
|
|
860
|
+
code, setCode,
|
|
861
|
+
scriptName, setScriptName,
|
|
862
|
+
params, setParams,
|
|
863
|
+
placement, setPlacement,
|
|
864
|
+
error, status, isRunning, hasActiveScript,
|
|
865
|
+
runScript, removeScript, resetCode,
|
|
866
|
+
exportScript, importScript,
|
|
867
|
+
defaultScript,
|
|
868
|
+
} = useScriptEditor();
|
|
869
|
+
```
|
|
870
|
+
|
|
871
|
+
#### Return type: `UseScriptEditorReturn`
|
|
872
|
+
|
|
873
|
+
| Property | Type | Description |
|
|
874
|
+
|----------|------|-------------|
|
|
875
|
+
| `code` | `string` | Current script source code |
|
|
876
|
+
| `setCode` | `(code: string) => void` | Update the source code |
|
|
877
|
+
| `scriptName` | `string` | Display name of the script |
|
|
878
|
+
| `setScriptName` | `(name: string) => void` | Update the name |
|
|
879
|
+
| `params` | `string` | Comma-separated numeric params (e.g. `"14, 26, 9"`) |
|
|
880
|
+
| `setParams` | `(params: string) => void` | Update params |
|
|
881
|
+
| `placement` | `ScriptPlacement` | `"main"` or `"sub"` |
|
|
882
|
+
| `setPlacement` | `(p: ScriptPlacement) => void` | Set placement |
|
|
883
|
+
| `error` | `string` | Last error message (empty = no error) |
|
|
884
|
+
| `status` | `string` | Last status message |
|
|
885
|
+
| `isRunning` | `boolean` | Whether the script is currently executing |
|
|
886
|
+
| `hasActiveScript` | `boolean` | Whether a script indicator is on the chart |
|
|
887
|
+
| `runScript` | `() => void` | Execute the script and register the indicator |
|
|
888
|
+
| `removeScript` | `() => void` | Remove the current script indicator from the chart |
|
|
889
|
+
| `resetCode` | `() => void` | Reset code to the default template |
|
|
890
|
+
| `exportScript` | `() => void` | Download the code as a `.js` file |
|
|
891
|
+
| `importScript` | `(file: File) => void` | Load a script from a file |
|
|
892
|
+
| `defaultScript` | `string` | The default template code |
|
|
893
|
+
|
|
894
|
+
#### Example script
|
|
895
|
+
|
|
896
|
+
```javascript
|
|
897
|
+
// Available: TA, dataList, params
|
|
898
|
+
const period = params[0] ?? 14;
|
|
899
|
+
const closes = dataList.map(d => d.close);
|
|
900
|
+
const highs = dataList.map(d => d.high);
|
|
901
|
+
const lows = dataList.map(d => d.low);
|
|
902
|
+
|
|
903
|
+
const rsi = TA.rsi(closes, period);
|
|
904
|
+
const boll = TA.bollinger(closes, period, 2);
|
|
905
|
+
|
|
906
|
+
// Return one object per candle — each key = one line on the chart
|
|
907
|
+
return rsi.map((v, i) => ({
|
|
908
|
+
rsi: v,
|
|
909
|
+
upper: boll.upper[i],
|
|
910
|
+
mid: boll.mid[i],
|
|
911
|
+
lower: boll.lower[i],
|
|
912
|
+
}));
|
|
913
|
+
```
|
|
914
|
+
|
|
915
|
+
---
|
|
916
|
+
|
|
917
|
+
### useWatchlist
|
|
918
|
+
|
|
919
|
+
Manage a list of tracked symbols with live price updates from your datafeed.
|
|
920
|
+
|
|
921
|
+
```typescript
|
|
922
|
+
import { useWatchlist } from "react-klinecharts-ui";
|
|
923
|
+
|
|
924
|
+
const {
|
|
925
|
+
items,
|
|
926
|
+
addSymbol,
|
|
927
|
+
removeSymbol,
|
|
928
|
+
switchSymbol,
|
|
929
|
+
activeSymbol,
|
|
930
|
+
} = useWatchlist();
|
|
931
|
+
```
|
|
932
|
+
|
|
933
|
+
#### Return type: `UseWatchlistReturn`
|
|
934
|
+
|
|
935
|
+
| Property | Type | Description |
|
|
936
|
+
|----------|------|-------------|
|
|
937
|
+
| `items` | `WatchlistItem[]` | Array of tracked symbols with price data |
|
|
938
|
+
| `addSymbol` | `(ticker: string) => void` | Add a symbol to the watchlist |
|
|
939
|
+
| `removeSymbol` | `(ticker: string) => void` | Remove a symbol from the watchlist |
|
|
940
|
+
| `switchSymbol` | `(ticker: string) => void` | Change the chart to display a symbol |
|
|
941
|
+
| `activeSymbol` | `string \| null` | Currently displayed symbol ticker |
|
|
942
|
+
|
|
943
|
+
#### WatchlistItem
|
|
944
|
+
|
|
945
|
+
| Property | Type | Description |
|
|
946
|
+
|----------|------|-------------|
|
|
947
|
+
| `ticker` | `string` | Symbol identifier |
|
|
948
|
+
| `lastPrice` | `number \| null` | Last traded price |
|
|
949
|
+
| `change` | `number \| null` | Absolute price change |
|
|
950
|
+
| `changePercent` | `number \| null` | 24h percentage change |
|
|
951
|
+
|
|
952
|
+
---
|
|
953
|
+
|
|
954
|
+
### useCompare
|
|
955
|
+
|
|
956
|
+
Compare multiple symbols on the same chart with individual colors and visibility toggle.
|
|
957
|
+
|
|
958
|
+
```typescript
|
|
959
|
+
import { useCompare } from "react-klinecharts-ui";
|
|
960
|
+
|
|
961
|
+
const {
|
|
962
|
+
symbols,
|
|
963
|
+
addSymbol,
|
|
964
|
+
removeSymbol,
|
|
965
|
+
toggleSymbol,
|
|
966
|
+
clearAll,
|
|
967
|
+
} = useCompare();
|
|
968
|
+
```
|
|
969
|
+
|
|
970
|
+
#### Return type: `UseCompareReturn`
|
|
971
|
+
|
|
972
|
+
| Property | Type | Description |
|
|
973
|
+
|----------|------|-------------|
|
|
974
|
+
| `symbols` | `CompareSymbol[]` | Array of comparison symbols with metadata |
|
|
975
|
+
| `addSymbol` | `(ticker: string) => void` | Add a symbol to compare |
|
|
976
|
+
| `removeSymbol` | `(ticker: string) => void` | Remove a comparison symbol |
|
|
977
|
+
| `toggleSymbol` | `(ticker: string) => void` | Toggle visibility of a symbol |
|
|
978
|
+
| `clearAll` | `() => void` | Remove all comparison symbols |
|
|
979
|
+
|
|
980
|
+
#### CompareSymbol
|
|
981
|
+
|
|
982
|
+
| Property | Type | Description |
|
|
983
|
+
|----------|------|-------------|
|
|
984
|
+
| `ticker` | `string` | Symbol identifier |
|
|
985
|
+
| `visible` | `boolean` | Whether the symbol is currently visible on chart |
|
|
986
|
+
| `color` | `string` | Hex color code for the symbol's line |
|
|
987
|
+
|
|
988
|
+
---
|
|
989
|
+
|
|
990
|
+
### useMeasure
|
|
991
|
+
|
|
992
|
+
Measure price changes, percentage swings, bar count, and time intervals between two points on the chart.
|
|
993
|
+
|
|
994
|
+
```typescript
|
|
995
|
+
import { useMeasure } from "react-klinecharts-ui";
|
|
996
|
+
|
|
997
|
+
const {
|
|
998
|
+
isActive,
|
|
999
|
+
startMeasure,
|
|
1000
|
+
cancelMeasure,
|
|
1001
|
+
result,
|
|
1002
|
+
} = useMeasure();
|
|
1003
|
+
```
|
|
1004
|
+
|
|
1005
|
+
#### Return type: `UseMeasureReturn`
|
|
1006
|
+
|
|
1007
|
+
| Property | Type | Description |
|
|
1008
|
+
|----------|------|-------------|
|
|
1009
|
+
| `isActive` | `boolean` | Whether measurement mode is enabled |
|
|
1010
|
+
| `startMeasure` | `() => void` | Enter measurement mode (click two points) |
|
|
1011
|
+
| `cancelMeasure` | `() => void` | Exit measurement mode |
|
|
1012
|
+
| `result` | `MeasureResult \| null` | Measurement data (null if not measured yet) |
|
|
1013
|
+
|
|
1014
|
+
#### MeasureResult
|
|
1015
|
+
|
|
1016
|
+
| Property | Type | Description |
|
|
1017
|
+
|----------|------|-------------|
|
|
1018
|
+
| `priceDiff` | `number` | Absolute price difference |
|
|
1019
|
+
| `pricePercent` | `number` | Percentage change |
|
|
1020
|
+
| `bars` | `number` | Number of bars between points |
|
|
1021
|
+
| `timeDiff` | `number` | Time difference in milliseconds |
|
|
1022
|
+
|
|
1023
|
+
---
|
|
1024
|
+
|
|
1025
|
+
### useAnnotations
|
|
1026
|
+
|
|
1027
|
+
Add text annotations at specific price levels and timestamps with optional colors.
|
|
1028
|
+
|
|
1029
|
+
```typescript
|
|
1030
|
+
import { useAnnotations } from "react-klinecharts-ui";
|
|
1031
|
+
|
|
1032
|
+
const {
|
|
1033
|
+
annotations,
|
|
1034
|
+
addAnnotation,
|
|
1035
|
+
removeAnnotation,
|
|
1036
|
+
updateAnnotation,
|
|
1037
|
+
clearAnnotations,
|
|
1038
|
+
} = useAnnotations();
|
|
1039
|
+
```
|
|
1040
|
+
|
|
1041
|
+
#### Return type: `UseAnnotationsReturn`
|
|
1042
|
+
|
|
1043
|
+
| Property | Type | Description |
|
|
1044
|
+
|----------|------|-------------|
|
|
1045
|
+
| `annotations` | `Annotation[]` | Array of all annotations |
|
|
1046
|
+
| `addAnnotation` | `(text, price, timestamp, color?) => string` | Add annotation; returns ID |
|
|
1047
|
+
| `removeAnnotation` | `(id: string) => void` | Remove annotation by ID |
|
|
1048
|
+
| `updateAnnotation` | `(id, updates) => void` | Update text or color |
|
|
1049
|
+
| `clearAnnotations` | `() => void` | Remove all annotations |
|
|
1050
|
+
|
|
1051
|
+
#### Annotation
|
|
1052
|
+
|
|
1053
|
+
| Property | Type | Description |
|
|
1054
|
+
|----------|------|-------------|
|
|
1055
|
+
| `id` | `string` | Unique identifier |
|
|
1056
|
+
| `text` | `string` | Annotation text |
|
|
1057
|
+
| `price` | `number` | Price level |
|
|
1058
|
+
| `timestamp` | `number` | Candle timestamp |
|
|
1059
|
+
| `color` | `string \| undefined` | Optional hex color |
|
|
1060
|
+
|
|
1061
|
+
---
|
|
1062
|
+
|
|
1063
|
+
### useReplay
|
|
1064
|
+
|
|
1065
|
+
Replay historical candles at various speeds with play/pause/step controls and progress tracking.
|
|
1066
|
+
|
|
1067
|
+
```typescript
|
|
1068
|
+
import { useReplay } from "react-klinecharts-ui";
|
|
1069
|
+
|
|
1070
|
+
const {
|
|
1071
|
+
isPlaying,
|
|
1072
|
+
speed,
|
|
1073
|
+
currentIndex,
|
|
1074
|
+
totalBars,
|
|
1075
|
+
play,
|
|
1076
|
+
pause,
|
|
1077
|
+
stop,
|
|
1078
|
+
step,
|
|
1079
|
+
setSpeed,
|
|
1080
|
+
} = useReplay();
|
|
1081
|
+
```
|
|
1082
|
+
|
|
1083
|
+
#### Return type: `UseReplayReturn`
|
|
1084
|
+
|
|
1085
|
+
| Property | Type | Description |
|
|
1086
|
+
|----------|------|-------------|
|
|
1087
|
+
| `isPlaying` | `boolean` | Whether replay is running |
|
|
1088
|
+
| `speed` | `number` | Current playback speed (0.25, 0.5, 1, 2, 4) |
|
|
1089
|
+
| `currentIndex` | `number` | Current bar index being displayed |
|
|
1090
|
+
| `totalBars` | `number` | Total bars in the dataset |
|
|
1091
|
+
| `play` | `() => void` | Start replay from current position |
|
|
1092
|
+
| `pause` | `() => void` | Pause replay (can resume with play) |
|
|
1093
|
+
| `stop` | `() => void` | Stop replay and reset to start |
|
|
1094
|
+
| `step` | `() => void` | Advance one bar when paused |
|
|
1095
|
+
| `setSpeed` | `(speed: number) => void` | Set playback speed multiplier |
|
|
1096
|
+
|
|
1097
|
+
---
|
|
1098
|
+
|
|
740
1099
|
## Utilities
|
|
741
1100
|
|
|
742
1101
|
### createDataLoader
|
|
@@ -787,6 +1146,33 @@ function ChartView() {
|
|
|
787
1146
|
|
|
788
1147
|
---
|
|
789
1148
|
|
|
1149
|
+
### TA (Technical Analysis)
|
|
1150
|
+
|
|
1151
|
+
A standalone math library for computing common technical indicators. Used internally by indicator templates and available to custom scripts via `useScriptEditor`.
|
|
1152
|
+
|
|
1153
|
+
```typescript
|
|
1154
|
+
import { TA } from "react-klinecharts-ui";
|
|
1155
|
+
```
|
|
1156
|
+
|
|
1157
|
+
| Function | Signature | Returns |
|
|
1158
|
+
|----------|-----------|---------|
|
|
1159
|
+
| `TA.sma` | `(data: number[], period: number)` | `number[]` — Simple Moving Average |
|
|
1160
|
+
| `TA.ema` | `(data: number[], period: number)` | `number[]` — Exponential Moving Average |
|
|
1161
|
+
| `TA.rma` | `(data: number[], period: number)` | `number[]` — Running (Wilder's) Moving Average |
|
|
1162
|
+
| `TA.wma` | `(data: number[], period: number)` | `number[]` — Weighted Moving Average |
|
|
1163
|
+
| `TA.hma` | `(data: number[], period: number)` | `number[]` — Hull Moving Average |
|
|
1164
|
+
| `TA.stdev` | `(data: number[], period: number)` | `number[]` — Standard Deviation |
|
|
1165
|
+
| `TA.rsi` | `(data: number[], period: number)` | `(number \| null)[]` — Relative Strength Index |
|
|
1166
|
+
| `TA.macd` | `(data: number[], fast?: number, slow?: number, signal?: number)` | `{ dif, dea, macd }` — each `(number \| null)[]` |
|
|
1167
|
+
| `TA.bollinger` | `(data: number[], period?: number, mult?: number)` | `{ upper, mid, lower }` — each `(number \| null)[]` |
|
|
1168
|
+
| `TA.tr` | `(highs: number[], lows: number[], closes: number[])` | `number[]` — True Range |
|
|
1169
|
+
| `TA.atr` | `(highs: number[], lows: number[], closes: number[], period: number)` | `number[]` — Average True Range |
|
|
1170
|
+
| `TA.vwap` | `(highs: number[], lows: number[], closes: number[], volumes: number[])` | `number[]` — Volume Weighted Average Price |
|
|
1171
|
+
| `TA.cci` | `(highs: number[], lows: number[], closes: number[], period: number)` | `number[]` — Commodity Channel Index |
|
|
1172
|
+
| `TA.stoch` | `(highs: number[], lows: number[], closes: number[], kPeriod?, kSmooth?, dPeriod?)` | `{ k, d }` — each `(number \| null)[]` |
|
|
1173
|
+
|
|
1174
|
+
---
|
|
1175
|
+
|
|
790
1176
|
## Data & Constants
|
|
791
1177
|
|
|
792
1178
|
All constants are exported from the root `index.ts`:
|
|
@@ -856,6 +1242,38 @@ type PriceAxisType = "normal" | "percentage" | "log";
|
|
|
856
1242
|
|
|
857
1243
|
---
|
|
858
1244
|
|
|
1245
|
+
## Custom Indicator Templates
|
|
1246
|
+
|
|
1247
|
+
11 TradingView-style indicator templates ported from [QUANTIX Extended Edition](https://github.com/dsavenk0/KLineChart-Pro). All are registered automatically via `registerExtensions`. Each template uses the `TA` library for calculations and includes custom `draw` functions for TradingView-like visual styling (gradient fills, dashed level lines, multi-color histograms).
|
|
1248
|
+
|
|
1249
|
+
```typescript
|
|
1250
|
+
import { indicators } from "react-klinecharts-ui";
|
|
1251
|
+
// indicators === [bollTv, cci, hma, ichimoku, maRibbon, macdTv, pivotPoints, rsiTv, stochastic, superTrend, vwap]
|
|
1252
|
+
```
|
|
1253
|
+
|
|
1254
|
+
### Main chart indicators
|
|
1255
|
+
|
|
1256
|
+
| Template | Name | Default params | Description |
|
|
1257
|
+
|----------|------|----------------|-------------|
|
|
1258
|
+
| `bollTv` | `BOLL_TV` | `[20, 2]` | Bollinger Bands — TradingView style with filled band area, SMA midline, and upper/lower bands |
|
|
1259
|
+
| `hma` | `HMA` | `[9]` | Hull Moving Average — high smoothing with minimal lag via `TA.hma()` |
|
|
1260
|
+
| `ichimoku` | `ICHIMOKU` | `[9, 26, 52, 26]` | Ichimoku Cloud — Tenkan-sen, Kijun-sen, Senkou Span A/B (filled cloud), Chikou Span |
|
|
1261
|
+
| `maRibbon` | `MA_RIBBON` | `[5, 10, 20, 30, 50, 100]` | Moving Average Ribbon — 6 EMAs with distinct colors for trend visualization |
|
|
1262
|
+
| `pivotPoints` | `PIVOT_POINTS` | `[1]` | Standard pivot with Pivot, R1, R2, S1, S2 levels as dashed horizontal lines |
|
|
1263
|
+
| `superTrend` | `SUPERTREND` | `[10, 3]` | ATR-based trend — dynamic green (up) / red (down) line coloring |
|
|
1264
|
+
| `vwap` | `VWAP` | `[]` | Volume Weighted Average Price — single blue line via `TA.vwap()` |
|
|
1265
|
+
|
|
1266
|
+
### Sub-pane indicators
|
|
1267
|
+
|
|
1268
|
+
| Template | Name | Default params | Description |
|
|
1269
|
+
|----------|------|----------------|-------------|
|
|
1270
|
+
| `macdTv` | `MACD_TV` | `[12, 26, 9]` | 4-color histogram: growing-positive (#26A69A), shrinking-positive (#B2DFDB), growing-negative (#FFCDD2), shrinking-negative (#EF5350). MACD line (#2962FF), Signal line (#FF6D00) |
|
|
1271
|
+
| `rsiTv` | `RSI_TV` | `[14, 14]` | RSI + MA line. Dashed levels at 70/50/30. Gradient fills in overbought (>70, red) and oversold (<30, green) zones |
|
|
1272
|
+
| `cci` | `CCI` | `[20]` | Commodity Channel Index via `TA.cci()` with dashed +100/0/-100 reference lines |
|
|
1273
|
+
| `stochastic` | `STOCHASTIC` | `[14, 1, 3]` | %K (#2962FF) and %D (#FF6D00) lines. Dashed 80/50/20 levels. Gradient fills in overbought/oversold zones |
|
|
1274
|
+
|
|
1275
|
+
---
|
|
1276
|
+
|
|
859
1277
|
## Drawing Overlays
|
|
860
1278
|
|
|
861
1279
|
`OverlayTemplate` instances for drawing tools. Automatically registered when `registerExtensions: true` (default).
|
|
@@ -881,6 +1299,15 @@ type PriceAxisType = "normal" | "percentage" | "log";
|
|
|
881
1299
|
| `anyWaves` | `"anyWaves"` | Custom wave pattern |
|
|
882
1300
|
| `abcd` | `"abcd"` | ABCD pattern |
|
|
883
1301
|
| `xabcd` | `"xabcd"` | XABCD pattern |
|
|
1302
|
+
| `elliottWave` | `"elliottWave"` | Elliott Wave (5-wave cycle with numbered vertices) |
|
|
1303
|
+
| `gannFan` | `"gannFan"` | Gann Fan (1x1, 1x2, etc.) |
|
|
1304
|
+
| `fibRetracement` | `"fibRetracement"` | Fibonacci retracement levels |
|
|
1305
|
+
| `parallelChannel` | `"parallelChannel"` | Parallel channel (two parallel lines) |
|
|
1306
|
+
| `longPosition` | `"longPosition"` | Long position risk/reward (TP/SL with % labels) |
|
|
1307
|
+
| `shortPosition` | `"shortPosition"` | Short position risk/reward (TP/SL with % labels) |
|
|
1308
|
+
| `measure` | `"measure"` | Measure tool (price %, bar count, time delta) |
|
|
1309
|
+
| `brush` | `"brush"` | Freehand brush drawing (Bezier smoothing) |
|
|
1310
|
+
| `ray` | `"ray"` | Infinite ray from a point |
|
|
884
1311
|
|
|
885
1312
|
---
|
|
886
1313
|
|
|
@@ -968,13 +1395,65 @@ interface OrderLinePadding {
|
|
|
968
1395
|
|
|
969
1396
|
All sub-interfaces (`OrderLineLineStyle`, `OrderLineMarkStyle`, `OrderLineLabelStyle`, `OrderLineFontStyle`, `OrderLinePadding`) are exported as named types from both the main and `extensions` entry points.
|
|
970
1397
|
|
|
1398
|
+
### depthOverlay
|
|
1399
|
+
|
|
1400
|
+
Overlay template for visualizing order book depth as horizontal liquidity bars at each price level. Shows cumulative buy/sell volume at price levels, useful for understanding support/resistance zones.
|
|
1401
|
+
|
|
1402
|
+
```typescript
|
|
1403
|
+
import { depthOverlay, KlinechartsUIProvider } from "react-klinecharts-ui/extensions";
|
|
1404
|
+
|
|
1405
|
+
<KlinechartsUIProvider overlays={[depthOverlay]}>...</KlinechartsUIProvider>;
|
|
1406
|
+
```
|
|
1407
|
+
|
|
1408
|
+
**Implementation details:**
|
|
1409
|
+
|
|
1410
|
+
- `needDefaultPointFigure: false`, `needDefaultXAxisFigure: false`, `needDefaultYAxisFigure: false` — entirely custom rendering
|
|
1411
|
+
- `createPointFigures` — draws rect figures at each price level using `yAxis.convertToPixel(price)` for positioning
|
|
1412
|
+
- `zLevel: -1` — renders behind the main candlestick data
|
|
1413
|
+
- Dynamic data via `extendData` — update with `chart.overrideOverlay({ id, extendData: newData })`
|
|
1414
|
+
|
|
1415
|
+
#### DepthOverlayExtendData
|
|
1416
|
+
|
|
1417
|
+
```typescript
|
|
1418
|
+
interface DepthOverlayExtendData {
|
|
1419
|
+
rows?: DepthOverlayRow[];
|
|
1420
|
+
/** Optional: customize buy side color. Default: "rgba(16, 186, 156, 0.3)" */
|
|
1421
|
+
buyColor?: string;
|
|
1422
|
+
/** Optional: customize sell side color. Default: "rgba(239, 68, 68, 0.3)" */
|
|
1423
|
+
sellColor?: string;
|
|
1424
|
+
}
|
|
1425
|
+
|
|
1426
|
+
interface DepthOverlayRow {
|
|
1427
|
+
price: number;
|
|
1428
|
+
buyVolume: number;
|
|
1429
|
+
sellVolume: number;
|
|
1430
|
+
}
|
|
1431
|
+
```
|
|
1432
|
+
|
|
1433
|
+
**Usage example:**
|
|
1434
|
+
|
|
1435
|
+
```typescript
|
|
1436
|
+
const chart = state.chart;
|
|
1437
|
+
if (chart) {
|
|
1438
|
+
const rows: DepthOverlayRow[] = [
|
|
1439
|
+
{ price: 40000, buyVolume: 5.2, sellVolume: 3.1 },
|
|
1440
|
+
{ price: 40100, buyVolume: 4.8, sellVolume: 4.2 },
|
|
1441
|
+
// ...
|
|
1442
|
+
];
|
|
1443
|
+
chart.overrideOverlay({
|
|
1444
|
+
id: "depthOverlay",
|
|
1445
|
+
extendData: { rows, buyColor: "rgba(34, 197, 94, 0.3)" },
|
|
1446
|
+
});
|
|
1447
|
+
}
|
|
1448
|
+
```
|
|
1449
|
+
|
|
971
1450
|
### overlays (array)
|
|
972
1451
|
|
|
973
1452
|
Array of all built-in drawing overlays — for direct access to the list:
|
|
974
1453
|
|
|
975
1454
|
```typescript
|
|
976
1455
|
import { overlays } from "react-klinecharts-ui";
|
|
977
|
-
// overlays === [arrow, circle, rect, triangle, ...] (
|
|
1456
|
+
// overlays === [arrow, circle, rect, triangle, ...] (26 items)
|
|
978
1457
|
```
|
|
979
1458
|
|
|
980
1459
|
---
|
|
@@ -1071,6 +1550,23 @@ export {
|
|
|
1071
1550
|
export { useScreenshot, type UseScreenshotReturn };
|
|
1072
1551
|
export { useFullscreen, type UseFullscreenReturn };
|
|
1073
1552
|
export { useOrderLines, type UseOrderLinesReturn, type OrderLineOptions };
|
|
1553
|
+
export {
|
|
1554
|
+
useUndoRedo,
|
|
1555
|
+
type UseUndoRedoReturn,
|
|
1556
|
+
type UndoRedoAction,
|
|
1557
|
+
type UndoRedoActionType,
|
|
1558
|
+
};
|
|
1559
|
+
export {
|
|
1560
|
+
useLayoutManager,
|
|
1561
|
+
type UseLayoutManagerReturn,
|
|
1562
|
+
type LayoutEntry,
|
|
1563
|
+
type ChartLayoutState,
|
|
1564
|
+
};
|
|
1565
|
+
export {
|
|
1566
|
+
useScriptEditor,
|
|
1567
|
+
type UseScriptEditorReturn,
|
|
1568
|
+
type ScriptPlacement,
|
|
1569
|
+
};
|
|
1074
1570
|
|
|
1075
1571
|
// Data
|
|
1076
1572
|
export { DEFAULT_PERIODS, type TerminalPeriod };
|
|
@@ -1091,36 +1587,39 @@ export {
|
|
|
1091
1587
|
export {
|
|
1092
1588
|
CANDLE_TYPES,
|
|
1093
1589
|
PRICE_AXIS_TYPES,
|
|
1590
|
+
YAXIS_POSITIONS,
|
|
1591
|
+
COMPARE_RULES,
|
|
1592
|
+
TOOLTIP_SHOW_RULES,
|
|
1094
1593
|
type CandleTypeOption,
|
|
1095
1594
|
type PriceAxisType,
|
|
1595
|
+
type YAxisPosition,
|
|
1596
|
+
type CompareRule,
|
|
1597
|
+
type TooltipShowRule,
|
|
1096
1598
|
};
|
|
1097
1599
|
|
|
1098
1600
|
// Utilities
|
|
1099
1601
|
export { createDataLoader };
|
|
1602
|
+
export { default as TA } from "./utils/TA";
|
|
1100
1603
|
|
|
1101
|
-
// Drawing overlays (all
|
|
1604
|
+
// Drawing overlays (all 26)
|
|
1102
1605
|
export {
|
|
1103
|
-
arrow,
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
gannBox,
|
|
1114
|
-
threeWaves,
|
|
1115
|
-
fiveWaves,
|
|
1116
|
-
eightWaves,
|
|
1117
|
-
anyWaves,
|
|
1118
|
-
abcd,
|
|
1119
|
-
xabcd,
|
|
1606
|
+
arrow, circle, rect, triangle, parallelogram,
|
|
1607
|
+
fibonacciCircle, fibonacciSegment, fibonacciSpiral,
|
|
1608
|
+
fibonacciSpeedResistanceFan, fibonacciExtension,
|
|
1609
|
+
fibRetracement,
|
|
1610
|
+
gannBox, gannFan,
|
|
1611
|
+
threeWaves, fiveWaves, eightWaves, anyWaves, elliottWave,
|
|
1612
|
+
abcd, xabcd,
|
|
1613
|
+
parallelChannel, ray,
|
|
1614
|
+
longPosition, shortPosition,
|
|
1615
|
+
measure, brush,
|
|
1120
1616
|
};
|
|
1121
1617
|
|
|
1618
|
+
// Custom indicator templates (all 11)
|
|
1619
|
+
export * from "./indicators";
|
|
1620
|
+
|
|
1122
1621
|
// Extensions
|
|
1123
|
-
export { registerExtensions, overlays, orderLine };
|
|
1622
|
+
export { registerExtensions, overlays, indicators, orderLine };
|
|
1124
1623
|
export type {
|
|
1125
1624
|
OrderLineExtendData,
|
|
1126
1625
|
OrderLineLineStyle,
|