@iccandle/news 0.0.1 → 0.0.3

package/README.md

@@ -35,7 +35,7 @@ function App() {
       widgetKey={widgetKey}
       defaultSymbol="XAU_USD"
       chartInterval="15"
-      theme="system"
+      theme="dark"
     >
       {/* Your chart container + TradingView bootstrap; call setChartWidget when ready */}
       <div id="tv_chart_container" style={{ height: "100%" }} />
@@ -131,13 +131,13 @@ const widgetKey = "your-iccandle-api-key";
   widgetKey={widgetKey}
   defaultSymbol="XAU_USD"
   chartInterval="15"
-  theme="system"
+  theme="dark"
 >
   <div ref={containerRef} style={{ height: "100%", minHeight: 400 }} />
 </NewsWidget>;
 ```
 
-When a news event is selected, the widget switches to a 50/50 split layout: the event analysis panel on the left and the chart (with pip-range overlays) on the right. On mobile (<1024px) the panels stack vertically.
+When a news event is selected, the widget switches to a 50/50 split layout: the event detail card and TradingView chart (with pip-range overlays) on the left, and the ICCandle iframe on the right. On mobile (<1024px) the panels stack vertically.
 
 ### Step 5 — Interact with news events
 
@@ -152,8 +152,7 @@ Once the widget is mounted:
 
 ### Theme and remote branding
 
-- **`theme="light"` / `"dark"`** — forces that palette for the widget chrome and chart overlays.
-- **`theme="system"`** (recommended when you don't control parent theme) — follows `prefers-color-scheme` for light/dark resolution.
+- **`theme="light"` / `"dark"` / `"system"`** — forces that palette for the widget chrome and chart overlays. `"system"` resolves automatically based on the user's OS `prefers-color-scheme` setting.
 - On mount, the widget fetches your org's tokens from ICCandle (see [Widget key and remote theming](#widget-key-and-remote-theming)) and sets CSS custom properties on the widget root, e.g. `--iccandle-primary`, `--iccandle-border`, so the event panel and chart overlays match your configured light/dark branding.
 
 ### Full working example
@@ -214,7 +213,7 @@ export function ChartWithNewsWidget() {
         widgetKey={WIDGET_KEY}
         defaultSymbol="XAU_USD"
         chartInterval="15"
-        theme="system"
+        theme="dark"
       >
         <div ref={containerRef} style={{ height: "100%", width: "100%" }} />
       </NewsWidget>
@@ -231,8 +230,7 @@ For a concrete in-repo reference (custom datafeed, timezone, visibility handling
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Full-page chart**                | Set the parent container to `height: 100vh` and let `NewsWidget` fill the space with `autosize: true`.                                                                         |
 | **Dashboard embed**                | Give the parent a fixed height (e.g. 600px) and `NewsWidget` handles the split layout internally.                                                                              |
-| **News / events on the time axis** | If your datafeed implements `getTimescaleMarks`, you can sync marks with `localStorage` — see [Optional: timescale marks (news/events)](#optional-timescale-marks-newsevents). |
-| **Custom symbol list**             | Pass any supported symbol as `defaultSymbol`; the widget supports 100+ forex, metals, indices, crypto, and commodity symbols.                                                  |
+| **News / events on the time axis** | If your datafeed implements `getTimescaleMarks`, you can sync marks with `localStorage` — see [Optional: timescale marks (news/events)](#optional-timescale-marks-newsevents). |                               |
 
 ### Troubleshooting
 
@@ -242,7 +240,7 @@ For a concrete in-repo reference (custom datafeed, timezone, visibility handling
 | `chartWidget` is always `null`   | Ensure you call `setChartWidget` after the widget is created (or inside `onChartReady` if your integration requires it).                                                                |
 | Event panel or theme looks wrong | Confirm `widgetKey` is valid; theme fetch uses `api-key: <widgetKey>`. Network or auth failures may leave defaults.                                                                     |
 | CORS / network errors on APIs    | In local dev, browser calls to ICCandle APIs may be blocked by CORS unless you proxy; the widget should still function with fallback styling—verify in production or behind your proxy. |
-| No events showing on chart       | The widget falls back to `XAU_USD` if `defaultSymbol` is unrecognized, but ensure `chartInterval` is one of the accepted values (`"1"`, `"5"`, `"15"`, `"30"`, `"60"`).                  |
+| No events showing on chart       | The widget falls back to the `defaultSymbol` if selected symbol is unrecognized, but ensure `chartInterval` is one of the accepted values (`"1"`, `"5"`, `"15"`, `"30"`, `"60"`).                  |
 
 ## API
 
@@ -250,8 +248,10 @@ For a concrete in-repo reference (custom datafeed, timezone, visibility handling
 
 | Name              | Kind      | Description                                       |
 | ----------------- | --------- | ------------------------------------------------- |
-| `NewsWidget`      | Component | Economic calendar analysis overlay for your chart |
-| `NewsWidgetProps` | Type      | Props for `NewsWidget`                            |
+| `NewsWidget`        | Component | Economic calendar analysis overlay for your chart |
+| `NewsWidgetProps`   | Type      | Props for `NewsWidget`                            |
+| `SymbolMapper`      | Type      | Mapping from ICCandle tickers to your broker's symbol names |
+| `ICCANDLE_TICKERS`  | Type      | Union of all ICCandle ticker strings (keys of `SymbolMapper`) |
 
 ### `NewsWidget` props
 
@@ -260,9 +260,10 @@ For a concrete in-repo reference (custom datafeed, timezone, visibility handling
 | `chartWidget`   | `IChartingLibraryWidget \| null`     | Yes      | Live TradingView widget instance (`null` until ready).                                                                      |
 | `children`      | `ReactNode`                          | Yes      | Your chart UI (e.g. container + library bootstrap).                                                                         |
 | `widgetKey`     | `string`                             | Yes      | ICCandle API key. Used for theme fetch, chart data, news events, and scanner validation.                                    |
-| `defaultSymbol` | `string`                             | Yes      | Default trading symbol (e.g. `"XAU_USD"`, `"EURUSD"`, `"BTCUSDT"`). Falls back to `"XAU_USD"` if the symbol is unrecognized or unavailable. |
-| `chartInterval` | `"1" \| "5" \| "15" \| "30" \| "60"` | Yes      | Chart candle interval in minutes. Defaults to `"15"`.                                                                       |
-| `theme`         | `"light" \| "dark" \| "system"`      | No       | Defaults to sensible behavior; `"system"` follows `prefers-color-scheme`. Affects resolved theme tokens and chart overlays. |
+| `defaultSymbol` | `string`                             | Yes      | Default trading symbol used to initialize the chart (e.g. `"XAU_USD"`, `"EURUSD"`, `"BTCUSDT"`). Also used as the fallback when a symbol is unrecognized, unmapped, or unavailable. |
+| `symbolMapper`  | `SymbolMapper`                       | No       | Maps ICCandle ticker names to your TradingView symbol names (e.g. `{ XAUUSD: "GOLD", USDCAD: "USD_CAD" }`). When omitted or when a ticker has no entry, the widget falls back to `defaultSymbol`. See [Symbol name mapping](#symbol-name-mapping-symbolmapper). |
+| `chartInterval` | `"1" \| "5" \| "15" \| "30" \| "60"` | Yes      | Initial chart candle interval in minutes used when showing the chart. Defaults to `"15"`.                                                                       |
+| `theme`         | `"light" \| "dark" \| "system"` | No       | Affects resolved theme tokens and chart overlays. `"system"` resolves to light or dark based on `prefers-color-scheme`. |
 
 ### Widget key and remote theming
 
@@ -273,7 +274,7 @@ On mount, the component loads branding colors from ICCandle:
 
 CSS custom properties (`--iccandle-primary`, `--iccandle-border`, `--iccandle-background`, `--iccandle-text`, etc.) are applied on the widget root so the event panel and chart overlays match your configured light/dark tokens.
 
-**Theme prop vs. API tokens:** The `theme` prop (`"light"` | `"dark"` | `"system"`) chooses which variant of those tokens to apply. `"system"` tracks `prefers-color-scheme` so the widget stays aligned with the user's OS preference when you don't pass an explicit light/dark mode from your app shell.
+**Theme prop vs. API tokens:** The `theme` prop (`"light"` | `"dark"` | `"system"`) chooses which variant of those tokens to apply.
 
 ### Behavior summary
 
@@ -286,9 +287,46 @@ CSS custom properties (`--iccandle-primary`, `--iccandle-border`, `--iccandle-ba
 - Stores selected events in `localStorage` (key `iccandle:current-news-event`) for timescale mark sync.
 - Listens for `window` `message` events for chart/news integration.
 
+### Chart switching between TradingView and ICCandle
+
+The widget dynamically switches between the third-party TradingView chart and ICCandle's own history chart depending on how much price data is available after the event:
+
+- **ICCandle history chart (elapsed events):** When a user clicks an older event where the selected timeframe has fully elapsed (roughly 50+ candles after the event time), the widget replaces the TradingView chart with ICCandle's history chart rendered via iframe. This chart provides ICCandle's curated pip-range analysis.
+- **TradingView chart (recent/upcoming events):** When the event's timeframe has not yet fully elapsed, the widget keeps the TradingView chart visible in a split layout — event detail card and TradingView chart on the left, ICCandle iframe on the right — and draws pip-range overlays directly on the TradingView chart.
+
+### Symbol handling and limitations
+
+ICCandle's history chart supports a fixed set of symbols. When a currency event occurs (e.g. a USD news release), only symbols related to that currency are available in the ICCandle chart, so the impact visualization is scoped to relevant pairs.
+
+In the TradingView chart, however, symbol filtering cannot be controlled by the widget — the impact is drawn on whatever symbol is currently active, which may not be directly related to the event's currency. Keep this in mind when interpreting pip-range overlays on unrelated symbols in the TradingView chart.
+
+#### Symbol name mapping (`symbolMapper`)
+
+ICCandle and your broker/TradingView setup often use different naming conventions for the same instrument — for example, ICCandle uses `XAUUSD` while your chart may use `GOLD`, or ICCandle uses `USDCAD` while your chart may use `USD_CAD`. The optional `symbolMapper` prop lets you define a mapping from ICCandle's ticker names to your chart's symbol names:
+
+```tsx
+<NewsWidget
+  chartWidget={chartWidget}
+  widgetKey="your-api-key"
+  defaultSymbol="XAUUSD"
+  chartInterval="15"
+  theme="dark"
+  symbolMapper={{
+    XAUUSD: "GOLD",
+    USDCAD: "USD_CAD",
+    EURUSD: "EURUSD",
+    // ... map ICCandle tickers to your broker's symbol names
+  }}
+>
+  {children}
+</NewsWidget>
+```
+
+When a symbol change event is received from the ICCandle iframe, the widget looks up the symbol in `symbolMapper`. If no mapping is found (or `symbolMapper` is not provided), the widget falls back to `defaultSymbol`. This ensures the TradingView chart always navigates to a valid symbol.
+
 ## Optional: timescale marks (news/events)
 
-If your data feed implements `getTimescaleMarks`, you can surface stored events (e.g. from `localStorage` under `tv:current-news-event`) as marks on the time axis. Example shape:
+If your data feed implements `getTimescaleMarks`, you can surface stored events (e.g. from `localStorage` under `iccandle:current-news-event`) as marks on the time axis. Example shape:
 
 ```ts
 getTimescaleMarks: async (