# @iccandle/widget-web-trading

React trading chart widget — order entry, terminal, and TradingView chart integration.

Published to npm as a library bundle. **Only `dist/` is included in the package** (`package.json` `"files": ["dist"]`). Source, `public/charting_library/`, and dev tooling are not shipped.

## Install

```bash
npm install @iccandle/widget-web-trading
```

**Peer dependencies** (install in your app if not already present):

```bash
npm install react react-dom
```

Supported: React 18 or 19.

## Usage

```tsx
import { WebTradingWidget } from "@iccandle/widget-web-trading";
import "@iccandle/widget-web-trading/style.css";

function TradingPage() {
  return (
    <div style={{ height: "100vh", width: "100%" }}>
      <WebTradingWidget
        baseUrl="https://your-api.example.com"
        token="your-auth-token"
      />
    </div>
  );
}
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `baseUrl` | `string` | yes | API base URL for widget requests |
| `token` | `string \| null` | no | Auth token; stored in `localStorage` under `web-trading-token` |
| `variant` | `"chart" \| "news"` | no | UI mode (default: `"chart"`) |
| `chartWidget` | `object \| null` | no | Host-owned TradingView widget instance (embed mode) |
| `scanResultUrl` | `string \| null` | no | Opens the side panel Scan Result tab with this URL |
| `onScanResultUrlChange` | `(url: string \| null) => void` | no | Called when scan result URL changes |
| `onScanResultLoad` | `() => void` | no | Called when the scan result iframe finishes loading |
| `scanOpen` | `boolean` | no | When `true`, opens the scan tab (sync with IC Candle scan button) |
| `onScanClick` | `(open: boolean) => void` | no | Called when scan tab opens (`true`) or closes (`false`) |
| `children` | `ReactNode` | no | Custom chart slot content (see embed mode below) |

### Embed mode (host-owned chart)

When your app already owns the TradingView widget instance, pass it via `chartWidget` and render your chart mount point as `children`. The widget will wire up order lines, symbol sync, and trading panels around your chart instead of creating its own.

```tsx
import { useEffect, useRef, useState } from "react";
import { WebTradingWidget } from "@iccandle/widget-web-trading";
import "@iccandle/widget-web-trading/style.css";

function TradingPageWithHostChart() {
  const containerRef = useRef<HTMLDivElement>(null);
  const [chartWidget, setChartWidget] = useState<object | null>(null);

  useEffect(() => {
    const container = containerRef.current;
    if (!container || !window.TradingView) {
      return;
    }

    const widget = new window.TradingView.widget({
      container,
      library_path: "/charting_library/",
      // datafeed, symbol, interval, etc.
    });

    widget.onChartReady(() => {
      setChartWidget(widget);
    });

    return () => {
      setChartWidget(null);
      widget.remove();
    };
  }, []);

  return (
    <div style={{ height: "100vh", width: "100%" }}>
      <WebTradingWidget
        baseUrl="https://your-api.example.com"
        token={token}
        chartWidget={chartWidget}
      >
        <div ref={containerRef} style={{ height: "100%", width: "100%" }} />
      </WebTradingWidget>
    </div>
  );
}
```

`chartWidget` must be the TradingView Charting Library widget instance from your host app. Pass `children` with the DOM element the chart is mounted into — omitting `children` leaves the chart slot empty.

### `ChartNewsOrdersOverlay`

A lighter overlay for news-style layouts:

```tsx
import { ChartNewsOrdersOverlay } from "@iccandle/widget-web-trading";

<ChartNewsOrdersOverlay
  baseUrl="https://your-api.example.com"
  onCreateNewOrder={() => { /* open order panel */ }}
/>
```

## Package exports

| Import | File |
|--------|------|
| `@iccandle/widget-web-trading` | `dist/web-trading-widget.js` (ESM) / `.cjs` (CJS) |
| `@iccandle/widget-web-trading/style.css` | `dist/web-trading-widget.css` |
| Types | `dist/web-trading-widget.d.ts` |

## TradingView charting library

The widget loads TradingView from `/charting_library/charting_library.js` at runtime. **This library is not part of the npm package.**

Your host app must serve the TradingView Charting Library assets (e.g. copy `charting_library/` into your `public/` folder) so they are available at `/charting_library/`.

## Local development

Clone the repo to work on the widget itself:

```bash
npm install
npm run dev
```

Open http://localhost:3002

The dev app uses `public/charting_library/` locally. Auth tokens can be set in `localStorage` (`web-trading-token`) or passed via the `token` prop.

## Build & publish

```bash
npm run build    # outputs to dist/
npm publish      # publishes dist/ only
```

`npm run build:app` builds the standalone Vite demo app (not published).

## Project structure (source repo)

- `components/dashboard/chart/new-order/web-trading-widget.entry.ts` — library entry
- `components/dashboard/chart/` — chart UI and trading panels
- `services/widget-api/` — API client
- `public/charting_library/` — TradingView assets (dev only, not published)
- `vite.lib.config.ts` — library build config