@iccandle/vuejs-widget 0.0.1

package/README.md

@@ -0,0 +1,236 @@
+# @iccandle/vuejs-widget
+
+Vue 3 component that wraps an existing [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/) widget and adds ICCandle’s **scanner UI**: a draggable popup to run pattern search over a user-selected bar range, with theming loaded from ICCandle’s API.
+
+Published as ESM and CommonJS; component styles are bundled and injected at runtime (no separate CSS import).
+
+## Install
+
+```bash
+npm install @iccandle/vuejs-widget
+# or
+pnpm add @iccandle/vuejs-widget
+```
+
+### How to get an API key
+
+1. Register or sign in at the [ICCandle corporate portal](https://corporate-iccandle.vercel.app/).
+2. Use **Create API key** in the dashboard.
+3. When selecting a service, choose **search** so the key is valid for this widget (remote theming, candle cache, and scanner validation).
+
+Issued keys use the format `icc_search_` followed by 48 hexadecimal characters.
+
+### Prerequisites
+
+- **Vue 3.5+** — `vue` is a **peer dependency** (install it in your app).
+- **TradingView Charting Library** — obtain it under your own license from TradingView, host the static assets (e.g. under `/charting_library/` in your public folder), and load the library at runtime. **This package does not ship the charting library.**
+- **ICCandle API key** — required for theme, candle cache, and scanner validation; format `icc_search_` plus 48 hex characters. See [How to get an API key](#how-to-get-an-api-key) above.
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import { shallowRef } from "vue";
+import type { IChartingLibraryWidget } from "charting_library/charting_library";
+import { WidgetIccandle } from "@iccandle/vuejs-widget";
+
+const chartWidget = shallowRef<IChartingLibraryWidget | null>(null);
+const widgetKey = "icc_search_..."; // ICCandle-issued key (48 hex chars after prefix)
+const iframeSrc = shallowRef("");
+
+function handleSubmit(src: string) {
+  iframeSrc.value = src;
+}
+</script>
+
+<template>
+  <WidgetIccandle
+    :chart-widget="chartWidget"
+    :widget-key="widgetKey"
+    theme="system"
+    user-id="your-user-id"
+    email="you@example.com"
+    :submit-callback="handleSubmit"
+  >
+    <template #default="{ chartRefs }">
+      <!-- Your chart container + TradingView bootstrap; set chartWidget when ready -->
+      <div id="tv_chart_container" style="height: 100%" />
+    </template>
+  </WidgetIccandle>
+  <iframe v-if="iframeSrc" :src="iframeSrc" title="ICCandle results" />
+</template>
+```
+
+Replace the chart placeholder with your TradingView initialization and pass the `IChartingLibraryWidget` instance when `onChartReady` (or equivalent) fires.
+
+## Usage guide
+
+### Step 1 — Install the package
+
+```bash
+npm install @iccandle/vuejs-widget
+```
+
+Ensure `vue` is installed and meets the peer version range.
+
+### Step 2 — Host the Charting Library
+
+1. Copy the TradingView Charting Library build into a path your app can serve as static files (e.g. `public/charting_library/` in Vite).
+2. Import the library constructor from that path in your bundler setup (see TradingView’s integration docs for your framework). The library is **not** bundled inside `@iccandle/vuejs-widget`; it loads at runtime via `library_path` (or equivalent) on the widget options.
+
+### Step 3 — Bootstrap TradingView and capture the widget instance
+
+```ts
+import { onMounted, onBeforeUnmount, ref, shallowRef } from "vue";
+import type {
+  ChartingLibraryWidgetOptions,
+  IChartingLibraryWidget,
+  ResolutionString,
+} from "charting_library/charting_library";
+import { widget } from "charting_library/charting_library";
+
+const LIBRARY_PATH = "/charting_library/"; // must match your hosted assets
+
+const containerRef = ref<HTMLDivElement | null>(null);
+const chartWidget = shallowRef<IChartingLibraryWidget | null>(null);
+
+onMounted(() => {
+  const el = containerRef.value;
+  if (!el) return;
+
+  const options: ChartingLibraryWidgetOptions = {
+    container: el,
+    library_path: LIBRARY_PATH,
+    symbol: "EURUSD",
+    interval: "60" as ResolutionString,
+    datafeed: yourDatafeed,
+    locale: "en",
+    autosize: true,
+  };
+
+  const tv = new widget(options);
+  chartWidget.value = tv;
+
+  onBeforeUnmount(() => {
+    try {
+      tv.remove();
+    } catch {
+      /* no-op */
+    }
+    chartWidget.value = null;
+  });
+});
+```
+
+You must supply a valid `datafeed`, `symbol`, `interval`, `locale`, and any other options required by your TradingView license and app.
+
+### Step 4 — Wrap the chart with `WidgetIccandle`
+
+`WidgetIccandle` must wrap the same subtree that contains the chart container so the scanner overlay positions correctly. Pass the live widget instance (or `null` while mounting):
+
+```vue
+<WidgetIccandle
+  :chart-widget="chartWidget"
+  :widget-key="widgetKey"
+  theme="system"
+  user-id="your-user-id"
+  email="you@example.com"
+  :submit-callback="(iframeSrc) => { /* see Step 5 */ }"
+>
+  <div ref="containerRef" style="height: 100%; min-height: 400px" />
+</WidgetIccandle>
+```
+
+### Step 5 — Handle the plugin iframe URL
+
+After a successful scan setup, `submitCallback` receives a **full HTTPS URL** for the ICCandle plugin iframe. The query string typically includes the bar window (timestamps / size), symbol, `candle_id`, `apiKey` (your widget key), resolved theme, and any active filters—use it as-is in an iframe `src` or deep link.
+
+**Open in a new tab**
+
+```ts
+submitCallback: (iframeSrc) => {
+  window.open(iframeSrc, "_blank", "noopener,noreferrer");
+}
+```
+
+**Show in a modal or side panel**
+
+Store the URL in state and render:
+
+```vue
+<iframe v-if="iframeSrc" title="ICCandle pattern search" :src="iframeSrc" />
+```
+
+### Theme and remote branding
+
+- **`theme="light"` / `"dark"`** — forces that palette for the scanner chrome and for values forwarded into the plugin URL.
+- **`theme="system"`** — follows `prefers-color-scheme` for light/dark resolution.
+- On mount, the widget fetches your org’s tokens from ICCandle and sets CSS custom properties on the widget root, e.g. `--iccandle-primary`, `--iccandle-border`.
+
+### Full working example
+
+See [`src/App.vue`](src/App.vue) and [`src/tradingview/TradingviewChart.vue`](src/tradingview/TradingviewChart.vue) in this repository’s dev app for a concrete in-repo reference (custom datafeed, timezone, visibility handling).
+
+## API
+
+### Exports
+
+| Name | Kind | Description |
+| ---- | ---- | ----------- |
+| `WidgetIccandle` | Component | Scanner overlay around your chart subtree |
+| `SelectorWidget` | Component | Deprecated alias of `WidgetIccandle` |
+| `WidgetIccandleChartRefs` | Type | Chart study refs for generated candles |
+| `withPlayChart` | Function | Wrap a datafeed for replay / predicted candles |
+| `getCustomIndicators` | Function | TradingView custom indicators for generated candles |
+| `getGeneratedCandlesMaskColor` | Function | Theme-aware mask color for predicted bars |
+
+### `WidgetIccandle` props
+
+| Prop | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `chartWidget` | `IChartingLibraryWidget \| null` | Yes | Live TradingView widget instance (`null` until ready). |
+| `widgetKey` | `string` | Yes | ICCandle API key (`icc_search_` + 48 hex chars). |
+| `submitCallback` | `(iframeSrc: string) => void` | Yes | Called after a successful scan setup with the plugin iframe URL. |
+| `userId` | `string` | Yes | User id forwarded to the results plugin. |
+| `email` | `string` | Yes | User email (pattern tracker). |
+| `widgetKeyPatternTracker` | `string` | No | Optional tracker API key (`icc_tracker_…`). |
+| `theme` | `"light" \| "dark" \| "system"` | No | Defaults to `"light"`. `"system"` follows `prefers-color-scheme`. |
+| `language` | `WidgetLanguage` | No | Scanner UI language (`en`, `zh`, `vi`, …). |
+| `onCloseResult` | `() => void` | No | Called when the results iframe posts `close-result`. |
+| `iframeLoaded` | `boolean` | No | Disables scanner actions while results iframe is loading. |
+
+Default slot receives `{ chartRefs }` for wiring custom indicators / generated-candle studies.
+
+### Widget key and remote theming
+
+On mount, the component loads branding colors from ICCandle:
+
+- **URL:** `https://api.iccandle.ai/corporate-client/v1/widgetStyle/search/user/?service_type=search`
+- **Header:** `api-key: <widgetKey>`
+
+CSS custom properties (`--iccandle-primary`, `--iccandle-border`, etc.) are applied on the widget root so the scanner matches your configured light/dark tokens.
+
+### Behavior summary
+
+- Subscribes to chart readiness, resolution, symbol changes, and drawing events.
+- Manages a `date_range` multipoint drawing so the user can adjust the bar window; window size and exported candles drive the scanner.
+- Posts candles to ICCandle’s cache endpoint before opening the plugin URL.
+- Listens for `window` `message` events for chart/news/pattern integration (replay, event marks, pattern selection) and can clear persisted news mark selections (`localStorage` keys `tv:selected-news-events`, `tv:clicked-news-event`) when starting a scan.
+
+## Optional: timescale marks (news/events)
+
+If your data feed implements `getTimescaleMarks`, you can surface stored events (e.g. from `localStorage` under `tv:selected-news-events`) as marks on the time axis. See the React sibling docs or `src/lib/data-feed.ts` in this repo for a working example.
+
+## Development (this repo)
+
+| Script | Command | Purpose |
+| ------ | ------- | ------- |
+| Dev demo | `pnpm dev` | Vite app with local charting library. |
+| Library build | `pnpm build` | Emits `dist/` (JS, CJS, bundled CSS injection, declarations). |
+| App build | `pnpm build:app` | Full demo app build. |
+
+`prepublishOnly` runs `build` before publish.
+
+## License
+
+MIT. TradingView Charting Library is subject to its own license from TradingView.

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import { Bar } from './tradingview-types/charting_library';
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { CustomIndicator } from '.././tradingview-types/charting_library';
+import { DefineComponent } from 'vue';
+import { EntityId } from './tradingview-types/charting_library';
+import { IBasicDataFeed } from './tradingview-types/charting_library';
+import { IChartingLibraryWidget } from './tradingview-types/charting_library';
+import { PublicProps } from 'vue';
+
+declare const __VLS_component: DefineComponent<__VLS_Props, {
+chartRefs: WidgetIccandleChartRefs;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+theme: "light" | "dark" | "system";
+iframeLoaded: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {
+rootEl: HTMLDivElement;
+}, HTMLDivElement>;
+
+declare type __VLS_Props = {
+    chartWidget: IChartingLibraryWidget | null;
+    theme?: "light" | "dark" | "system";
+    language?: WidgetLanguage;
+    onCloseResult?: () => void;
+    iframeLoaded?: boolean;
+};
+
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {
+            chartRefs: WidgetIccandleChartRefs;
+        }): any;
+    };
+    refs: {
+        rootEl: HTMLDivElement;
+    };
+    rootEl: HTMLDivElement;
+};
+
+declare type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+
+declare type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type ChartItem = {
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+    timestamp: number;
+    v?: number;
+};
+
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export { _default as SelectorWidget }
+export { _default as WidgetIccandle }
+
+export declare type GeneratedCandlesTheme = "light" | "dark";
+
+export declare const getCustomIndicators: (theme?: GeneratedCandlesTheme) => Promise<readonly CustomIndicator[]>;
+
+/** Pane-matching mask color so predicted bars hide the underlying series. */
+export declare const getGeneratedCandlesMaskColor: (theme?: GeneratedCandlesTheme) => string;
+
+/** @deprecated Use `WidgetIccandleChartRefs`. */
+export declare type SelectorWidgetChartRefs = WidgetIccandleChartRefs;
+
+export declare type TradingViewCandleType = ChartItem;
+
+declare const WIDGET_LANGUAGES: readonly ["en", "zh", "vi", "th", "ko", "ja", "mn", "ru"];
+
+export declare type WidgetIccandleChartRefs = {
+    highlightBarsRef: {
+        current: Bar[];
+    };
+    generatedCandlesBackgroundStudyIdRef: {
+        current: EntityId | null;
+    };
+    generatedCandlesStudyIdRef: {
+        current: EntityId | null;
+    };
+};
+
+/** Props for the published `WidgetIccandle` component. */
+export declare type WidgetIccandleProps = {
+    chartWidget: IChartingLibraryWidget | null;
+    theme?: "light" | "dark" | "system";
+    language?: WidgetLanguage;
+    onCloseResult?: () => void;
+    iframeLoaded?: boolean;
+};
+
+export declare type WidgetLanguage = (typeof WIDGET_LANGUAGES)[number];
+
+export declare function withPlayChart<T extends IBasicDataFeed>(datafeed: T): T;
+
+export declare function withPlayChart<A extends unknown[]>(factory: (...args: A) => IBasicDataFeed, ...args: A): IBasicDataFeed;
+
+export { }