@nabeeltahirdeveloper/chart-sdk 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,302 @@
+# @nabeeltahirdeveloper/chart-sdk
+
+TradingView-style chart SDK for React with real-time data, trading controls, and drawing tools.
+
+## Installation
+
+```bash
+npm install @nabeeltahirdeveloper/chart-sdk
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom
+```
+
+## Quick Start
+
+```jsx
+import { TradingProvider, Chart, TradingToolbar } from '@nabeeltahirdeveloper/chart-sdk'
+
+function App() {
+  return (
+    <TradingProvider baseUrl="https://your-api-url.com">
+      <TradingToolbar />
+      <Chart />
+    </TradingProvider>
+  )
+}
+```
+
+## Components
+
+All components must be rendered inside a `<TradingProvider>`.
+
+### TradingProvider
+
+Wraps your app and provides trading state (symbols, prices, orders, drawing tools, etc).
+
+```jsx
+<TradingProvider baseUrl="https://your-api-url.com">
+  {children}
+</TradingProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `baseUrl` | `string` | API server URL |
+| `children` | `ReactNode` | Child components |
+
+### Chart
+
+Full-featured candlestick chart with real-time price updates, order lines, and drawing tools.
+
+```jsx
+<Chart />
+```
+
+### TradingToolbar
+
+Unified toolbar that combines all trading controls in a single row. This is the easiest way to add all controls at once.
+
+```jsx
+<TradingToolbar />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showCoinSelector` | `boolean` | `true` | Show/hide coin selector |
+| `showVolumeControl` | `boolean` | `true` | Show/hide volume control |
+| `showStopLoss` | `boolean` | `true` | Show/hide stop loss |
+| `showTakeProfit` | `boolean` | `true` | Show/hide take profit |
+| `showDrawingTools` | `boolean` | `true` | Show/hide drawing tools |
+| `showDividers` | `boolean` | `true` | Show dividers between sections |
+| `volume` | `number` | - | Controlled volume value |
+| `onVolumeChange` | `function` | - | Volume change callback |
+| `stopLoss` | `string` | - | Controlled stop loss value |
+| `onStopLossChange` | `function` | - | Stop loss change callback |
+| `stopLossEnabled` | `boolean` | - | Controlled SL toggle state |
+| `onStopLossEnabledChange` | `function` | - | SL toggle callback |
+| `takeProfit` | `string` | - | Controlled take profit value |
+| `onTakeProfitChange` | `function` | - | Take profit change callback |
+| `takeProfitEnabled` | `boolean` | - | Controlled TP toggle state |
+| `onTakeProfitEnabledChange` | `function` | - | TP toggle callback |
+| `coinSelectorProps` | `object` | `{}` | Props passed to CoinSelector |
+| `volumeControlProps` | `object` | `{}` | Props passed to VolumeControl |
+| `stopLossProps` | `object` | `{}` | Props passed to StopLoss |
+| `takeProfitProps` | `object` | `{}` | Props passed to TakeProfit |
+| `drawingToolsProps` | `object` | `{}` | Props passed to DrawingTools |
+| `style` | `object` | - | Custom inline styles |
+| `className` | `string` | - | Custom CSS class |
+
+### CoinSelector
+
+Searchable dropdown to select trading symbols. Symbols are categorized into Forex/Metals and Crypto. Reads from `TradingContext` automatically.
+
+```jsx
+import { CoinSelector } from '@nabeeltahirdeveloper/chart-sdk'
+
+<CoinSelector />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `style` | `object` | Custom inline styles |
+| `className` | `string` | Custom CSS class |
+
+### VolumeControl
+
+Numeric input with increment/decrement buttons and preset lot-size chips. Works as controlled or uncontrolled component.
+
+```jsx
+import { VolumeControl } from '@nabeeltahirdeveloper/chart-sdk'
+
+// Uncontrolled (manages its own state)
+<VolumeControl />
+
+// Controlled
+const [volume, setVolume] = useState(0.1)
+<VolumeControl value={volume} onChange={setVolume} />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | - | Controlled value |
+| `onChange` | `function` | - | Change callback `(value: number) => void` |
+| `min` | `number` | `0.01` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `0.01` | Step increment |
+| `presets` | `number[]` | `[0.01, 0.05, 0.1, 0.5, 1.0]` | Preset buttons |
+| `showPresets` | `boolean` | `true` | Show preset buttons |
+| `showLabel` | `boolean` | `true` | Show "Vol" label |
+| `label` | `string` | `"Vol"` | Custom label text |
+| `style` | `object` | - | Custom inline styles |
+| `className` | `string` | - | Custom CSS class |
+
+### StopLoss
+
+Stop loss input with toggle switch and price/pips mode. Red themed.
+
+```jsx
+import { StopLoss } from '@nabeeltahirdeveloper/chart-sdk'
+
+// Uncontrolled
+<StopLoss />
+
+// Controlled
+const [sl, setSl] = useState('')
+const [slEnabled, setSlEnabled] = useState(false)
+<StopLoss value={sl} onChange={setSl} enabled={slEnabled} onEnabledChange={setSlEnabled} />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | - | Controlled price/pips value |
+| `onChange` | `function` | - | Value change callback |
+| `enabled` | `boolean` | - | Controlled toggle state |
+| `onEnabledChange` | `function` | - | Toggle callback |
+| `mode` | `string` | - | Controlled mode: `"price"` or `"pips"` |
+| `onModeChange` | `function` | - | Mode change callback |
+| `showToggle` | `boolean` | `true` | Show on/off toggle |
+| `showModeSwitch` | `boolean` | `true` | Show Price/Pips toggle |
+| `showLabel` | `boolean` | `true` | Show "SL" label |
+| `label` | `string` | `"SL"` | Custom label text |
+| `style` | `object` | - | Custom inline styles |
+| `className` | `string` | - | Custom CSS class |
+
+### TakeProfit
+
+Take profit input with toggle switch and price/pips mode. Green themed. Same API as StopLoss.
+
+```jsx
+import { TakeProfit } from '@nabeeltahirdeveloper/chart-sdk'
+
+// Uncontrolled
+<TakeProfit />
+
+// Controlled
+const [tp, setTp] = useState('')
+const [tpEnabled, setTpEnabled] = useState(false)
+<TakeProfit value={tp} onChange={setTp} enabled={tpEnabled} onEnabledChange={setTpEnabled} />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | - | Controlled price/pips value |
+| `onChange` | `function` | - | Value change callback |
+| `enabled` | `boolean` | - | Controlled toggle state |
+| `onEnabledChange` | `function` | - | Toggle callback |
+| `mode` | `string` | - | Controlled mode: `"price"` or `"pips"` |
+| `onModeChange` | `function` | - | Mode change callback |
+| `showToggle` | `boolean` | `true` | Show on/off toggle |
+| `showModeSwitch` | `boolean` | `true` | Show Price/Pips toggle |
+| `showLabel` | `boolean` | `true` | Show "TP" label |
+| `label` | `string` | `"TP"` | Custom label text |
+| `style` | `object` | - | Custom inline styles |
+| `className` | `string` | - | Custom CSS class |
+
+### DrawingTools
+
+Toolbar with chart drawing tool buttons. Wired to chart context automatically.
+
+Available tools: Crosshair, Trend Line, Parallel Channel, Fibonacci, Rectangle, Price Level.
+
+```jsx
+import { DrawingTools } from '@nabeeltahirdeveloper/chart-sdk'
+
+<DrawingTools />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showLabel` | `boolean` | `true` | Show "Draw" label |
+| `showDelete` | `boolean` | `true` | Show delete all button |
+| `showVisibility` | `boolean` | `true` | Show visibility toggle |
+| `label` | `string` | `"Draw"` | Custom label text |
+| `style` | `object` | - | Custom inline styles |
+| `className` | `string` | - | Custom CSS class |
+
+## Using Components Individually
+
+Import and compose components however you like:
+
+```jsx
+import {
+  TradingProvider,
+  Chart,
+  CoinSelector,
+  VolumeControl,
+  StopLoss,
+  TakeProfit,
+  DrawingTools,
+} from '@nabeeltahirdeveloper/chart-sdk'
+
+function App() {
+  const [volume, setVolume] = useState(0.1)
+
+  return (
+    <TradingProvider baseUrl="https://your-api-url.com">
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <CoinSelector />
+        <VolumeControl value={volume} onChange={setVolume} />
+        <StopLoss />
+        <TakeProfit />
+        <DrawingTools />
+      </div>
+      <Chart />
+    </TradingProvider>
+  )
+}
+```
+
+## Utilities
+
+```jsx
+import {
+  useTrading,
+  setChartBaseUrl,
+  setSocketBaseUrl,
+} from '@nabeeltahirdeveloper/chart-sdk'
+```
+
+### useTrading()
+
+React hook that returns the full trading context:
+
+```jsx
+const {
+  selectedSymbol,
+  setSelectedSymbol,
+  selectedTimeframe,
+  setSelectedTimeframe,
+  symbols,
+  symbolsLoading,
+  orders,
+  userBalance,
+  activeTool,
+  setActiveTool,
+  chartObjects,
+  setChartObjects,
+  drawingsVisible,
+  setDrawingsVisible,
+  showGrid,
+  setShowGrid,
+  chartType,
+  setChartType,
+  currentSymbolData,
+  accountSummary,
+} = useTrading()
+```
+
+### setChartBaseUrl(url)
+
+Set the base URL for chart API requests.
+
+### setSocketBaseUrl(url)
+
+Set the base URL for WebSocket connections.
+
+## License
+
+ISC