@iccandle/news 0.0.2 → 0.0.4

package/README.md

@@ -137,7 +137,7 @@ const widgetKey = "your-iccandle-api-key";
 </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,7 +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="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
@@ -248,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
 
@@ -258,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 used to initialize the chart (e.g. `"XAU_USD"`, `"EURUSD"`, `"BTCUSDT"`). Also used as the fallback when a selected symbol is unrecognized or unavailable. |
+| `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" \|`      | Yes       | Affects resolved theme tokens and chart overlays. |
+| `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
 
@@ -271,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"`) chooses which variant of those tokens to apply.
+**Theme prop vs. API tokens:** The `theme` prop (`"light"` | `"dark"` | `"system"`) chooses which variant of those tokens to apply.
 
 ### Behavior summary
 
@@ -284,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 (