@iccandle/vuejs-widget 0.2.0 → 0.2.1

package/README.md

@@ -214,6 +214,25 @@ Scan and Pattern Tracker require `localStorage.iccandle_token`. The results ifra
 
 The root uses CSS custom properties you can override: `--iccandle-primary`, `--iccandle-border`, `--iccandle-text`, `--iccandle-background`, `--iccandle-primary-gradient-end`, `--iccandle-font`.
 
+### Chart mask colors
+
+During replay the widget draws all predicted candles at once and hides the ones that have not been revealed yet by painting them in a solid "mask" color. The illusion only works if that color is identical to the chart pane background, otherwise the hidden bars show up as visible blocks ahead of the replay cursor.
+
+Defaults are `#ffffff` for `light` and `#0F0F0F` for `dark`. If your TradingView `paneProperties.background` differs, pass `chartMaskColors` with the matching value:
+
+```vue
+<WidgetIccandle
+  :chart-widget="chartWidget"
+  :submit-callback="handleSubmit"
+  theme="dark"
+  :chart-mask-colors="{ dark: '#2F2F2F', light: '#ffffff' }"
+>
+  <div ref="containerRef" style="height: 100%" />
+</WidgetIccandle>
+```
+
+Only the entry for the active theme is used, and each key is optional — omit one to keep its default. Any CSS color string the charting library accepts works, but avoid transparency: a translucent mask lets the real series bleed through. Changing the prop recreates the generated-candle studies, so it can be updated reactively when the host switches themes.
+
 ### Language
 
 `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.
@@ -241,6 +260,7 @@ See [`src/App.vue`](src/App.vue), [`src/tradingview/TradingviewChart.vue`](src/t
 | ---- | ---- | ----------- |
 | `WidgetIccandle` | Component | Scanner overlay around your chart subtree. |
 | `WidgetIccandleProps` | Type | Public props of `WidgetIccandle`. |
+| `WidgetChartMaskColors` | Type | `{ light?: string; dark?: string }` for the `chartMaskColors` prop. |
 | `WidgetLanguage` | Type | Supported UI languages. |
 | `withPlayChart` | Function | Wrap a TradingView datafeed (or factory) so replay can inject bars and block live ticks. |
 | `getCustomIndicators` | Function | Returns custom studies used to draw generated / predicted candles. Pass `"light"` or `"dark"`. |
@@ -260,6 +280,7 @@ See [`src/App.vue`](src/App.vue), [`src/tradingview/TradingviewChart.vue`](src/t
 | `chartWidget` | `IChartingLibraryWidget \| null` | Yes | — | Live TradingView widget (`null` until ready). |
 | `submitCallback` | `(iframeSrc: string) => void` | Yes | — | Called with the embed URL after a scan (and for some pricing / news navigations). |
 | `theme` | `"light" \| "dark" \| "system"` | No | `"light"` | Scanner and forwarded embed theme. |
+| `chartMaskColors` | `WidgetChartMaskColors` | No | `{ light: "#ffffff", dark: "#0F0F0F" }` | Per-theme color used to mask not-yet-revealed predicted candles. Must match your chart pane background. |
 | `language` | `WidgetLanguage` | No | `"en"` | Scanner UI language. |
 | `onCloseResult` | `() => void` | No | — | Called when the embed posts `selector.closeResult`. |
 | `iframeLoaded` | `boolean` | No | `true` | When `false`, Scan and Pattern Tracker are disabled. Set `true` after the results iframe has loaded. |

package/dist/index.d.ts

@@ -24,6 +24,8 @@ declare type __VLS_Props = {
     chartWidget: IChartingLibraryWidget | null;
     submitCallback: (iframeSrc: string) => void;
     theme?: "light" | "dark" | "system";
+    /** Simulate-candle mask colors per theme. Defaults: light `#ffffff`, dark `#0F0F0F`. */
+    chartMaskColors?: WidgetChartMaskColors;
     language?: WidgetLanguage;
     onCloseResult?: () => void;
     iframeLoaded?: boolean;
@@ -64,6 +66,9 @@ declare type __VLS_WithTemplateSlots<T, S> = T & {
     };
 };
 
+/** Same origin + path → soft update via postMessage (no iframe remount). */
+export declare function canSoftSelectorNavigate(iframe: HTMLIFrameElement | null | undefined, nextSrc: string): boolean;
+
 export declare type GeneratedCandlesTheme = "light" | "dark";
 
 export declare const getCustomIndicators: (theme?: GeneratedCandlesTheme) => Promise<readonly CustomIndicator[]>;
@@ -84,10 +89,33 @@ export declare function postOpenPricingToParent(options?: Pick<OpenPricingMessag
 
 export declare function postOpenPricingToWindow(target: Window, options?: Pick<OpenPricingMessage, "theme" | "language">): void;
 
+export declare function postSelectorLoadingToEmbed(iframe: HTMLIFrameElement | null | undefined, isLoading: boolean): boolean;
+
+export declare function postSelectorScanToEmbed(iframe: HTMLIFrameElement | null | undefined, url: string): boolean;
+
+export declare const SELECTOR_LOADING_MESSAGE_TYPE = "selector-loading";
+
+export declare const SELECTOR_SCAN_MESSAGE_TYPE = "selector-scan";
+
+export declare type SelectorLoadingMessage = {
+    type: typeof SELECTOR_LOADING_MESSAGE_TYPE;
+    isLoading: boolean;
+};
+
+export declare type SelectorScanMessage = {
+    type: typeof SELECTOR_SCAN_MESSAGE_TYPE;
+    url: string;
+};
+
 declare const WIDGET_LANGUAGES: readonly ["en", "zh", "vi", "th", "ko", "ja", "mn", "ru"];
 
 export declare const WIDGET_RESULT_URL = "https://embed-iccandle-app.iccandle.ai";
 
+export declare type WidgetChartMaskColors = {
+    light?: string;
+    dark?: string;
+};
+
 export declare const WidgetIccandle: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 
 declare type WidgetIccandleChartRefs = {
@@ -107,6 +135,8 @@ export declare type WidgetIccandleProps = {
     chartWidget: IChartingLibraryWidget | null;
     submitCallback: (iframeSrc: string) => void;
     theme?: "light" | "dark" | "system";
+    /** Simulate-candle mask colors per theme. Defaults: light `#ffffff`, dark `#0F0F0F`. */
+    chartMaskColors?: WidgetChartMaskColors;
     language?: WidgetLanguage;
     onCloseResult?: () => void;
     iframeLoaded?: boolean;