@iccandle/vuejs-widget 0.3.3 → 0.4.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 CHANGED
@@ -1,8 +1,33 @@
1
1
  # @iccandle/vuejs-widget
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/@iccandle/vuejs-widget.svg)](https://www.npmjs.com/package/@iccandle/vuejs-widget)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@iccandle/vuejs-widget.svg)](https://www.npmjs.com/package/@iccandle/vuejs-widget)
5
+ [![license](https://img.shields.io/npm/l/@iccandle/vuejs-widget.svg)](#license)
6
+ ![vue](https://img.shields.io/badge/vue-%5E3.5-42b883)
7
+
3
8
  Vue 3 scanner overlay for an existing [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/) widget. It adds ICCandle’s draggable scanner popup, pattern search, replay of predicted candles, and a results embed.
4
9
 
5
- Published as ESM and CommonJS. Component styles are bundled and injected at runtime — no separate CSS import.
10
+ Published as ESM and CommonJS with TypeScript declarations. Component styles are bundled and injected at runtime — no separate CSS import.
11
+
12
+ ## Features
13
+
14
+ - **Pattern scanner** — select a range on the chart and search for similar historical patterns across forex, commodities, indices, crypto, and stocks.
15
+ - **AI simulation replay** — predicted candles are revealed bar by bar on your chart, skipping closed sessions (e.g. the FX weekend) so 2H/4H bars stay on the chart grid.
16
+ - **Correlated markets panel** — while a simulation is on the chart, the popup expands to show how the move is expected to ripple into correlated markets (ρ, direction, % move).
17
+ - **Pattern Tracker** — subscribe to alerts when a selected pattern forms again.
18
+ - **News / event overlays** — event marks, vertical lines, and event-anchored simulations.
19
+ - **Theming** — light, dark, or system, CSS custom properties, and client styles from the ICCandle Plugin Portal via `apiKey`.
20
+ - **8 UI languages** — `en`, `zh`, `vi`, `th`, `ko`, `ja`, `mn`, `ru`.
21
+
22
+ ## Contents
23
+
24
+ - [Install](#install)
25
+ - [Prerequisites](#prerequisites)
26
+ - [Quick start](#quick-start)
27
+ - [Usage](#usage)
28
+ - [API](#api)
29
+ - [Troubleshooting](#troubleshooting)
30
+ - [Changelog](#changelog)
6
31
 
7
32
  ## Install
8
33
 
@@ -212,7 +237,41 @@ Scan and Pattern Tracker require `localStorage.iccandle_token`. The results ifra
212
237
  | `"dark"` | Dark scanner chrome; adds `.iccandle-dark` on the root. |
213
238
  | `"system"` | Follows `prefers-color-scheme`. |
214
239
 
215
- The root uses CSS custom properties you can override: `--iccandle-primary`, `--iccandle-border`, `--iccandle-text`, `--iccandle-background`, `--iccandle-primary-gradient-end`, `--iccandle-font`.
240
+ The root uses CSS custom properties you can override: `--iccandle-primary`, `--iccandle-border`, `--iccandle-text`, `--iccandle-background`, `--iccandle-primary-gradient-end`, `--iccandle-font`. `--iccandle-secondary` is derived from the background.
241
+
242
+ ### Plugin Portal style (`apiKey`)
243
+
244
+ Clients manage their style in the ICCandle Plugin Portal and create an API key there. Pass it to the widget:
245
+
246
+ ```vue
247
+ <WidgetIccandle api-key="<KEY>" :chart-widget="chartWidget" :submit-callback="handleSubmit">
248
+ <!-- chart -->
249
+ </WidgetIccandle>
250
+ ```
251
+
252
+ - The widget calls `GET https://api.iccandle.ai/plugin-client/v1/plugin/style` with the `api-key` header once per key. The result is cached in memory and refetched only when `apiKey` changes (not on theme change). The request times out after 5 s and is aborted on unmount.
253
+ - The key is also forwarded to every results-iframe URL as `&apiKey=`, so the embed app uses the same style.
254
+ - The key is **publishable**: it only reads style data and is meant to ship in client-side code. Restrict it in the portal with **allowed origins** (`scheme://host[:port]`, e.g. `https://app.example.com`). With no allowed origins any site can use the key (the portal warns about this). Requests from other origins get `403` and the widget falls back to the defaults.
255
+
256
+ Supported style fields, per theme (`light` and `dark`):
257
+
258
+ | Field | CSS variable | Accepted values |
259
+ | ----- | ------------ | --------------- |
260
+ | `iccandle_primary` | `--iccandle-primary` | `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb(r, g, b)`, `rgba(r, g, b, a)` |
261
+ | `iccandle_primary_gradient_end` | `--iccandle-primary-gradient-end` | same as above |
262
+ | `iccandle_background` | `--iccandle-background` | same as above |
263
+ | `iccandle_border` | `--iccandle-border` | same as above |
264
+ | `iccandle_text` | `--iccandle-text` | same as above |
265
+ | `icc_font` | `--iccandle-font` | `Inter Tight`, `Inter`, `Roboto`, `Open Sans`, `Lato`, `Montserrat`, `Poppins`, `Nunito`, `Source Sans 3`, `IBM Plex Sans`, `system-ui` |
266
+
267
+ The portal also sets `default_theme` (`light` \| `dark`). The widget re-validates every value and ignores anything outside the formats above. Non-system fonts are loaded once from Google Fonts.
268
+
269
+ **Priority** (highest first):
270
+
271
+ 1. Theme: `theme` prop → portal `default_theme` → `light`.
272
+ 2. Colors: portal style → bundled defaults.
273
+
274
+ **Fallback:** with no `apiKey`, an invalid or revoked key, a disallowed origin, rate limiting, no saved style, or a network error, the widget uses the bundled defaults. The chart keeps working and nothing is thrown.
216
275
 
217
276
  ### Chart mask colors
218
277
 
@@ -237,6 +296,16 @@ Only the entry for the active theme is used, and each key is optional — omit o
237
296
 
238
297
  `language` accepts `"en"` | `"zh"` | `"vi"` | `"th"` | `"ko"` | `"ja"` | `"mn"` | `"ru"`. Unknown values fall back to `"en"`. The value is used for scanner copy and is forwarded into embed URLs.
239
298
 
299
+ ### Correlated markets panel
300
+
301
+ When the embed sends a `chart.play` message whose `data.correlation` holds a correlation payload (`root` symbol plus `simulations[0].symbols`), the scanner popup expands under its toolbar once the simulated candles finish drawing. The panel lists the first four markets, with a "Show all" toggle for the rest. Each row shows:
302
+
303
+ - the correlation coefficient `ρ` (hover for a sentence such as "EUR/USD 82% correlated with XAU/USD"),
304
+ - an `inverse` tag when the market moves against the root symbol,
305
+ - the expected % move.
306
+
307
+ No host configuration is needed. The panel hides itself when replay stops, the result is closed, or the payload has no symbols. It switches to a compact layout when the popup is narrow.
308
+
240
309
  ### Layout helpers
241
310
 
242
311
  Injected CSS includes split-pane classes used in the demo:
@@ -279,7 +348,8 @@ See [`src/App.vue`](src/App.vue), [`src/tradingview/TradingviewChart.vue`](src/t
279
348
  | ---- | ---- | -------- | ------- | ----------- |
280
349
  | `chartWidget` | `IChartingLibraryWidget \| null` | Yes | — | Live TradingView widget (`null` until ready). |
281
350
  | `submitCallback` | `(iframeSrc: string) => void` | Yes | — | Called with the embed URL after a scan (and for some pricing / news navigations). |
282
- | `theme` | `"light" \| "dark" \| "system"` | No | `"light"` | Scanner and forwarded embed theme. |
351
+ | `theme` | `"light" \| "dark" \| "system"` | No | portal `default_theme`, else `"light"` | Scanner and forwarded embed theme. |
352
+ | `apiKey` | `string` | No | — | Publishable Plugin Portal key (`pk_live_…`). Loads the client's portal style and forwards `&apiKey=` to the results iframe. See [Plugin Portal style](#plugin-portal-style-apikey). |
283
353
  | `chartMaskColors` | `WidgetChartMaskColors` | No | `{ light: "#ffffff", dark: "#0F0F0F" }` | Per-theme color used to mask not-yet-revealed predicted candles. Must match your chart pane background. |
284
354
  | `language` | `WidgetLanguage` | No | `"en"` | Scanner UI language. |
285
355
  | `onCloseResult` | `() => void` | No | — | Called when the embed posts `selector.closeResult`. |
@@ -307,7 +377,7 @@ The widget handles JSON messages with a `name` (and optional `data`) from the re
307
377
 
308
378
  | Name | Effect |
309
379
  | ---- | ------ |
310
- | `chart.play` | Replay / predicted candles on the chart. |
380
+ | `chart.play` | Replay / predicted candles on the chart. Optional `data.correlation` feeds the correlated markets panel. |
311
381
  | `chart.stop` | Stop replay and restore live ticks. |
312
382
  | `chart.requestResolution` | Re-post the current chart resolution to the iframe. |
313
383
  | `selector.closeResult` | Invoke `onCloseResult`. |
@@ -326,11 +396,39 @@ The host → embed helpers use a different shape: `{ type: "parent-origin" | "pa
326
396
 
327
397
  If your datafeed implements `getTimescaleMarks`, you can surface stored events from `localStorage` (`tv:selected-news-events`, `tv:clicked-news-event`) as marks on the time axis. See [`src/lib/data-feed.ts`](src/lib/data-feed.ts) in this repo.
328
398
 
399
+ ## Troubleshooting
400
+
401
+ | Symptom | Check |
402
+ | ------- | ----- |
403
+ | Scanner popup never appears | `chartWidget` is still `null`, `isShowScannerPopup` is `false`, or the current resolution is not in `availableIntervals`. |
404
+ | Scan / Pattern Tracker are greyed out | `iframeLoaded` is `false` or a scan is still loading. Set `iframeLoaded` to `true` from the iframe's `load` event. |
405
+ | "Please log in first" on every click | `localStorage.iccandle_token` is missing. Make sure `handleResultIframeLoad(iframe)` runs on load so the embed can post `auth.signIn`. |
406
+ | Hidden predicted candles show up as blocks | `chartMaskColors` does not match your chart pane background. See [Chart mask colors](#chart-mask-colors). |
407
+ | Messages from the embed are ignored | The widget only accepts `postMessage` from `WIDGET_RESULT_URL`. Don't proxy the embed through another origin. |
408
+
409
+ ## Changelog
410
+
411
+ ### 0.4.0
412
+
413
+ - **Breaking:** removed the `bg_dark` / `bg_light` props. Use a Plugin Portal style via `apiKey` instead.
414
+ - New `apiKey` prop loads the client's Plugin Portal style (colors, font, default theme) and forwards `&apiKey=` to the results iframe.
415
+ - Without an explicit `theme`, the portal's `default_theme` is used, then `light`.
416
+ - Buttons and inputs inherit the widget font.
417
+
418
+ ### 0.3.4
419
+
420
+ - Correlated markets panel under the scanner popup during AI simulation replay.
421
+ - Simulated bars past the last real candle stay on the chart's resolution grid and skip closed sessions.
422
+ - Removed the paid custom window-size dropdown from the popup. The toolbar now uses equal-width controls.
423
+ - Tooltips are positioned in the viewport, so they no longer get clipped by the popup or chart.
424
+ - Scanner symbol selection ignores tickers that are not in the catalog and keeps a stable order.
425
+ - Symbol search trigger has a fixed height, and chips no longer wrap.
426
+
329
427
  ## Development (this repo)
330
428
 
331
429
  | Script | Command | Purpose |
332
430
  | ------ | ------- | ------- |
333
- | Dev demo | `pnpm dev` | Vite app with a local charting library. |
431
+ | Dev demo | `pnpm dev` | Vite app with a local charting library. Copy `.env.example` to `.env` for demo sign-in. |
334
432
  | Library build | `pnpm build` | Emits `dist/` (ESM, CJS, injected CSS, declarations). |
335
433
  | App build | `pnpm build:app` | Full demo app build. |
336
434
 
package/dist/index.d.ts CHANGED
@@ -13,7 +13,6 @@ import { Ref } from 'vue';
13
13
  declare const __VLS_component: DefineComponent<__VLS_Props, {
14
14
  chartRefs: WidgetIccandleChartRefs;
15
15
  }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
16
- theme: "light" | "dark" | "system";
17
16
  iframeLoaded: boolean;
18
17
  isShowScanButton: boolean;
19
18
  isShowTrackerButton: boolean;
@@ -28,9 +27,14 @@ declare type __VLS_Props = {
28
27
  theme?: "light" | "dark" | "system";
29
28
  /** Simulate-candle mask colors per theme. Defaults: light `#ffffff`, dark `#0F0F0F`. */
30
29
  chartMaskColors?: WidgetChartMaskColors;
31
- /** Widget + embed background (hex, `#` optional). Omitted = CSS defaults. */
32
- bg_dark?: string;
33
- bg_light?: string;
30
+ /**
31
+ * Publishable Plugin Portal API key (`pk_live_…`). When set, the widget loads
32
+ * the client's portal style (colors, font, default theme) and forwards the
33
+ * key to the results iframe as `&apiKey=`. An explicit `theme` prop takes
34
+ * priority over the portal's default theme. Any failure falls
35
+ * back to the bundled defaults.
36
+ */
37
+ apiKey?: string;
34
38
  language?: WidgetLanguage;
35
39
  onCloseResult?: () => void;
36
40
  iframeLoaded?: boolean;
@@ -169,9 +173,14 @@ export declare type WidgetIccandleProps = {
169
173
  theme?: "light" | "dark" | "system";
170
174
  /** Simulate-candle mask colors per theme. Defaults: light `#ffffff`, dark `#0F0F0F`. */
171
175
  chartMaskColors?: WidgetChartMaskColors;
172
- /** Widget + embed background (hex, `#` optional). Omitted = CSS defaults. */
173
- bg_dark?: string;
174
- bg_light?: string;
176
+ /**
177
+ * Publishable Plugin Portal API key (`pk_live_…`). When set, the widget loads
178
+ * the client's portal style (colors, font, default theme) and forwards the
179
+ * key to the results iframe as `&apiKey=`. An explicit `theme` prop takes
180
+ * priority over the portal's default theme. Any failure falls
181
+ * back to the bundled defaults.
182
+ */
183
+ apiKey?: string;
175
184
  language?: WidgetLanguage;
176
185
  onCloseResult?: () => void;
177
186
  iframeLoaded?: boolean;