react-klinecharts-ui 0.6.0 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 **react-klinecharts-ui** is a headless React library for building financial trading terminals on top of [klinecharts](https://github.com/liihuu/KLineChart). It provides a state provider, a set of hooks, and overlay templates. No UI components are included — use any UI framework you prefer.
 
-**[Live Demo](https://nemezzizz.github.io/react-klinecharts-ui/)**
+**[Live Demo](https://nemezzizz.github.io/tradedash/)** · **[Examples](https://nemezzizz.github.io/react-klinecharts-ui/examples/)**
 
 ### Acknowledgments
 
@@ -62,13 +62,24 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
 ## Installation
 
 ```bash
-npm install react-klinecharts-ui react-klinecharts
+npm install react-klinecharts-ui klinecharts
 # or with pnpm
-pnpm add react-klinecharts-ui react-klinecharts
+pnpm add react-klinecharts-ui klinecharts
 # or with yarn
-yarn add react-klinecharts-ui react-klinecharts
+yarn add react-klinecharts-ui klinecharts
 ```
 
+> **Rendering a chart?** `react-klinecharts-ui` is headless — it does not render
+> the canvas itself. The fastest path is the optional `ChartCanvas` wrapper,
+> which needs `react-klinecharts`:
+>
+> ```bash
+> npm install react-klinecharts-ui klinecharts react-klinecharts
+> ```
+>
+> You can also initialise the chart yourself with `klinecharts.init()` and skip
+> `react-klinecharts` entirely — see [Renderer-agnostic](#renderer-agnostic).
+
 ---
 
 ## Concept
@@ -82,6 +93,170 @@ The library follows a **headless** pattern — all UI is written by the consumer
 
 All hooks must be called inside `<KlinechartsUIProvider>`.
 
+### Renderer-agnostic
+
+`react-klinecharts-ui` is **headless** — it owns state (symbol, period, indicators, alerts, replay, …) and drives a klinecharts `Chart` instance, but it does **not** render the canvas. The only bridge between a renderer and the provider is a single dispatch:
+
+```ts
+dispatch({ type: "SET_CHART", chart });
+```
+
+Once the chart instance is registered, every hook (`useIndicators`, `useAlerts`, `useReplay`, …) reads and mutates it via `state.chart.*`. You can initialise that instance **three ways**:
+
+**1. `ChartCanvas` (fastest, optional peer `react-klinecharts`)** — the thin wrapper shipped at `react-klinecharts-ui/chart` wires the `<KLineChart>` renderer, builds the data loader, forwards symbol/period/theme from provider state, and dispatches `SET_CHART` for you:
+
+```tsx
+import { KlinechartsUIProvider } from "react-klinecharts-ui";
+import { ChartCanvas } from "react-klinecharts-ui/chart";
+
+<KlinechartsUIProvider datafeed={datafeed} defaultSymbol={symbol} defaultTheme="dark">
+  <ChartCanvas className="h-[500px]" />
+</KlinechartsUIProvider>;
+```
+
+**2. `<KLineChart>` from `react-klinecharts` directly** — full control over props, at the cost of writing the `onReady` bridge yourself:
+
+```tsx
+import { useMemo } from "react";
+import { KLineChart } from "react-klinecharts";
+import { useKlinechartsUI, createDataLoader } from "react-klinecharts-ui";
+
+function ChartView() {
+  const { state, dispatch, datafeed } = useKlinechartsUI();
+  const dataLoader = useMemo(() => createDataLoader(datafeed, dispatch), [datafeed, dispatch]);
+  return (
+    <KLineChart
+      dataLoader={dataLoader}
+      symbol={state.symbol ?? undefined}
+      period={state.period}
+      styles={state.theme}
+      onReady={(chart) => dispatch({ type: "SET_CHART", chart })}
+    />
+  );
+}
+```
+
+**3. Direct `klinecharts.init()` (no `react-klinecharts` at all)** — for custom lifecycles, SSR/Next.js, or when you want zero extra dependencies:
+
+```tsx
+import { useEffect, useRef } from "react";
+import { init, dispose } from "klinecharts";
+import { useKlinechartsUI } from "react-klinecharts-ui";
+
+function ChartView() {
+  const { dispatch, datafeed } = useKlinechartsUI();
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const chart = init(ref.current!);
+    dispatch({ type: "SET_CHART", chart });          // the bridge
+    chart!.applyNewData(/* load bars yourself */);
+    return () => dispose(ref.current!);
+  }, []);
+  return <div ref={ref} style={{ height: 500 }} />;
+}
+```
+
+Whatever route you pick, the hooks work the same — they only care about the `Chart` instance in the store.
+
+### Persistence
+
+By default, user-facing state (alerts, chart settings, the active indicator
+set) lives only in memory and is **lost on page reload**. Pass a `storage`
+option to the provider to hydrate it on mount and write it back on every
+change. The adapter mirrors the Web Storage API, so `localStorage` works out
+of the box:
+
+```tsx
+<KlinechartsUIProvider datafeed={datafeed} storage={{}}>
+  {/* alerts / settings / indicators now survive refresh */}
+</KlinechartsUIProvider>
+```
+
+`storage={{}}` uses the defaults: `localStorage` adapter, the `alerts` /
+`settings` / `indicators` namespaces, and a `"rkui:"` key prefix. You can
+override any of them — e.g. plug in a remote or IndexedDB-backed adapter:
+
+```tsx
+import type { StorageAdapter } from "react-klinecharts-ui";
+
+const remoteAdapter: StorageAdapter = {
+  getItem: (key) => mySyncCache.get(key) ?? null,
+  setItem: (key, value) => {
+    mySyncCache.set(key, value);
+    flushToServer(key, value); // async, fire-and-forget
+  },
+  removeItem: (key) => { mySyncCache.delete(key); deleteFromServer(key); },
+};
+
+<KlinechartsUIProvider datafeed={datafeed} storage={{ adapter: remoteAdapter }}>
+```
+
+**Scope.** The adapter covers the reducer store today: `alerts`, `settings`
+(`useKlinechartsUISettings`), and `indicators` (the active lists, pane ids,
+axis bindings, and visibility). Per-hook `useState` values — script code
+(`useScriptEditor`), compared symbols (`useCompare`), watchlist, annotations —
+are not yet covered by the adapter and remain in memory. `useLayoutManager`
+(named snapshot presets) is orthogonal: it serializes the whole chart
+(indicators + drawings + meta) on demand to its own keys, independent of the
+live `storage` adapter.
+
+The adapter contract is **synchronous** (matching the Web Storage API). For
+async backends, keep a synchronous in-memory cache and flush in the
+background — the provider reads/writes through `getItem`/`setItem` only.
+
+---
+
+### Workspace & multi-chart
+
+`KlinechartsUIProvider` owns exactly one chart. To render a **grid** of charts
+that share crosshair / scroll / zoom / symbol / period, wrap several providers
+in a `WorkspaceProvider` and drop a `useChartSync` bridge inside each:
+
+```tsx
+import {
+  KlinechartsUIProvider,
+  WorkspaceProvider,
+  useChartSync,
+  useWorkspace,
+} from "react-klinecharts-ui";
+
+const cells = [
+  { id: "a", symbol: { ticker: "BTCUSDT" }, period: { span: 1, type: "minute", label: "1m" } },
+  { id: "b", symbol: { ticker: "ETHUSDT" }, period: { span: 1, type: "minute", label: "1m" } },
+];
+
+// Rendered inside each KlinechartsUIProvider — registers its chart with the
+// workspace and mirrors viewport events to siblings.
+function ChartSyncBridge({ cellId }: { cellId: string }) {
+  useChartSync({ cellId });
+  return null;
+}
+
+<WorkspaceProvider defaultCells={cells}>
+  <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr" }}>
+    {cells.map((c) => (
+      <KlinechartsUIProvider key={c.id} datafeed={datafeed} defaultSymbol={c.symbol} defaultPeriod={c.period}>
+        <ChartSyncBridge cellId={c.id} />
+        <ChartCanvas />
+      </KlinechartsUIProvider>
+    ))}
+  </div>
+</WorkspaceProvider>
+```
+
+`useChartSync` mirrors crosshair / scroll / zoom between the registered charts
+using only the **public** klinecharts API (`executeAction`, `scrollToTimestamp`,
+`setBarSpace`) — no internal `_chartStore`. A re-entrancy guard prevents
+feedback loops. Per-channel sync can be disabled via the `sync` prop
+(`{ scroll: false }`).
+
+> **Scope of this foundation.** Each cell keeps its own alerts, replay, and
+> drawings (per-provider). Hoisting shared alerts/replay/drawings to the
+> workspace level, plus tabbed layouts and server-persisted workspaces, is
+> planned. Read the
+> [multi-chart example](https://nemezzizz.github.io/react-klinecharts-ui/examples/multi-chart/)
+> for a runnable 2×2 grid.
+
 ---
 
 ## KlinechartsUIProvider
@@ -1480,7 +1655,6 @@ import { TA } from "react-klinecharts-ui";
 | `TA.atr` | `(highs: number[], lows: number[], closes: number[], period: number)` | `number[]` — Average True Range |
 | `TA.vwap` | `(highs: number[], lows: number[], closes: number[], volumes: number[])` | `number[]` — Volume Weighted Average Price |
 | `TA.cci` | `(highs: number[], lows: number[], closes: number[], period: number)` | `number[]` — Commodity Channel Index |
-| `TA.stoch` | `(highs: number[], lows: number[], closes: number[], kPeriod?, kSmooth?, dPeriod?)` | `{ k, d }` — each `(number \| null)[]` |
 
 ---
 
@@ -1692,7 +1866,9 @@ interface OrderLineExtendData {
 }
 
 interface OrderLineLineStyle {
-  style?: "solid" | "dashed" | "dotted"; // Default: "dashed"
+  // klinecharts only supports "solid" and "dashed"; a dotted effect is done
+  // via `dashedValue` (e.g. [2, 2]).
+  style?: "solid" | "dashed"; // Default: "dashed"
   width?: number; // Default: 1
   dashedValue?: [number, number]; // Default: [4, 2]
 }
@@ -2083,4 +2259,8 @@ export type {
   DepthOverlayExtendData,
   DepthOverlayRow,
 };
+
+// Chart entry (optional — peer-depends on react-klinecharts).
+// import from "react-klinecharts-ui/chart"
+export { ChartCanvas, type ChartCanvasProps };
 ```

package/dist/chart.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+var chunkF24D6PWY_cjs = require('./chunk-F24D6PWY.cjs');
+require('./chunk-Q7SFCCGT.cjs');
+var react = require('react');
+var reactKlinecharts = require('react-klinecharts');
+var jsxRuntime = require('react/jsx-runtime');
+
+function ChartCanvas({
+  className,
+  children,
+  options,
+  styles
+}) {
+  const { state, dispatch, datafeed } = chunkF24D6PWY_cjs.useKlinechartsUI();
+  const dataLoader = react.useMemo(
+    () => chunkF24D6PWY_cjs.createDataLoader(datafeed, dispatch),
+    [datafeed, dispatch]
+  );
+  const mainIndicatorsRef = react.useRef(state.mainIndicators);
+  const subIndicatorsRef = react.useRef(state.subIndicators);
+  react.useEffect(() => {
+    mainIndicatorsRef.current = state.mainIndicators;
+    subIndicatorsRef.current = state.subIndicators;
+  }, [state.mainIndicators, state.subIndicators]);
+  const handleReady = react.useCallback(
+    (chart) => {
+      dispatch({ type: "SET_CHART", chart });
+      mainIndicatorsRef.current.forEach((name) => {
+        chart.createIndicator(
+          { name, id: `main_${name}` },
+          { isStack: true, pane: { id: "candle_pane" } }
+        );
+      });
+      const subUpdates = {};
+      Object.keys(subIndicatorsRef.current).forEach((name) => {
+        const id = `sub_${name}`;
+        chart.createIndicator({ name, id });
+        const ind = chart.getIndicators({ id })[0];
+        if (ind?.paneId) subUpdates[name] = ind.paneId;
+      });
+      if (Object.keys(subUpdates).length > 0) {
+        dispatch({
+          type: "SET_SUB_INDICATORS",
+          indicators: { ...subIndicatorsRef.current, ...subUpdates }
+        });
+      }
+    },
+    [dispatch]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    reactKlinecharts.KLineChart,
+    {
+      className,
+      options,
+      styles: styles ?? state.theme,
+      dataLoader,
+      symbol: state.symbol ?? void 0,
+      period: state.period,
+      locale: state.locale,
+      timezone: state.timezone,
+      onReady: handleReady,
+      children
+    }
+  );
+}
+
+exports.ChartCanvas = ChartCanvas;
+//# sourceMappingURL=chart.cjs.map
+//# sourceMappingURL=chart.cjs.map

package/dist/chart.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/chart/ChartCanvas.tsx"],"names":["useKlinechartsUI","useMemo","createDataLoader","useRef","useEffect","useCallback","jsx","KLineChart"],"mappings":";;;;;;;;AAsDO,SAAS,WAAA,CAAY;AAAA,EAC1B,SAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAA,EAAgC;AAC9B,EAAA,MAAM,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,KAAaA,kCAAA,EAAiB;AAEvD,EAAA,MAAM,UAAA,GAAaC,aAAA;AAAA,IACjB,MAAMC,kCAAA,CAAiB,QAAA,EAAU,QAAQ,CAAA;AAAA,IACzC,CAAC,UAAU,QAAQ;AAAA,GACrB;AAKA,EAAA,MAAM,iBAAA,GAAoBC,YAAA,CAAO,KAAA,CAAM,cAAc,CAAA;AACrD,EAAA,MAAM,gBAAA,GAAmBA,YAAA,CAAO,KAAA,CAAM,aAAa,CAAA;AACnD,EAAAC,eAAA,CAAU,MAAM;AACd,IAAA,iBAAA,CAAkB,UAAU,KAAA,CAAM,cAAA;AAClC,IAAA,gBAAA,CAAiB,UAAU,KAAA,CAAM,aAAA;AAAA,EACnC,GAAG,CAAC,KAAA,CAAM,cAAA,EAAgB,KAAA,CAAM,aAAa,CAAC,CAAA;AAE9C,EAAA,MAAM,WAAA,GAAcC,iBAAA;AAAA,IAClB,CAAC,KAAA,KAAiB;AAEhB,MAAA,QAAA,CAAS,EAAE,IAAA,EAAM,WAAA,EAAa,KAAA,EAAO,CAAA;AAIrC,MAAA,iBAAA,CAAkB,OAAA,CAAQ,OAAA,CAAQ,CAAC,IAAA,KAAS;AAC1C,QAAA,KAAA,CAAM,eAAA;AAAA,UACJ,EAAE,IAAA,EAAM,EAAA,EAAI,CAAA,KAAA,EAAQ,IAAI,CAAA,CAAA,EAAG;AAAA,UAC3B,EAAE,OAAA,EAAS,IAAA,EAAM,MAAM,EAAE,EAAA,EAAI,eAAc;AAAE,SAC/C;AAAA,MACF,CAAC,CAAA;AAED,MAAA,MAAM,aAAqC,EAAC;AAC5C,MAAA,MAAA,CAAO,KAAK,gBAAA,CAAiB,OAAO,CAAA,CAAE,OAAA,CAAQ,CAAC,IAAA,KAAS;AACtD,QAAA,MAAM,EAAA,GAAK,OAAO,IAAI,CAAA,CAAA;AACtB,QAAA,KAAA,CAAM,eAAA,CAAgB,EAAE,IAAA,EAAM,EAAA,EAAI,CAAA;AAClC,QAAA,MAAM,MAAM,KAAA,CAAM,aAAA,CAAc,EAAE,EAAA,EAAI,EAAE,CAAC,CAAA;AACzC,QAAA,IAAI,GAAA,EAAK,MAAA,EAAQ,UAAA,CAAW,IAAI,IAAI,GAAA,CAAI,MAAA;AAAA,MAC1C,CAAC,CAAA;AACD,MAAA,IAAI,MAAA,CAAO,IAAA,CAAK,UAAU,CAAA,CAAE,SAAS,CAAA,EAAG;AACtC,QAAA,QAAA,CAAS;AAAA,UACP,IAAA,EAAM,oBAAA;AAAA,UACN,YAAY,EAAE,GAAG,gBAAA,CAAiB,OAAA,EAAS,GAAG,UAAA;AAAW,SAC1D,CAAA;AAAA,MACH;AAAA,IACF,CAAA;AAAA,IACA,CAAC,QAAQ;AAAA,GACX;AAEA,EAAA,uBACEC,cAAA;AAAA,IAACC,2BAAA;AAAA,IAAA;AAAA,MACC,SAAA;AAAA,MACA,OAAA;AAAA,MACA,MAAA,EAAQ,UAAU,KAAA,CAAM,KAAA;AAAA,MACxB,UAAA;AAAA,MACA,MAAA,EAAQ,MAAM,MAAA,IAAU,MAAA;AAAA,MACxB,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,UAAU,KAAA,CAAM,QAAA;AAAA,MAChB,OAAA,EAAS,WAAA;AAAA,MAER;AAAA;AAAA,GACH;AAEJ","file":"chart.cjs","sourcesContent":["import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  type ReactNode,\n} from \"react\";\nimport { KLineChart } from \"react-klinecharts\";\nimport type { Chart, Options, DeepPartial, Styles } from \"klinecharts\";\nimport {\n  useKlinechartsUI,\n} from \"../provider/ChartTerminalContext\";\nimport { createDataLoader } from \"../utils/createDataLoader\";\n\nexport interface ChartCanvasProps {\n  /** className applied to the chart container div. */\n  className?: string;\n  /**\n   * Optional children rendered inside `<KLineChart>` (use the `<Widget>`\n   * component from `react-klinecharts` to portal React into chart DOM layers).\n   */\n  children?: ReactNode;\n  /**\n   * Chart initialization options, applied once on mount. Forwarded to\n   * `<KLineChart>` as the `options` prop.\n   */\n  options?: Options;\n  /**\n   * Styles override applied on mount and whenever it changes. Forwarded to\n   * `<KLineChart>` as the `styles` prop.\n   */\n  styles?: string | DeepPartial<Styles>;\n}\n\n/**\n * Thin renderer wrapper for `react-klinecharts-ui`.\n *\n * `react-klinecharts-ui` is **headless / renderer-agnostic**: it only needs a\n * klinecharts `Chart` instance to be registered via\n * `dispatch({ type: \"SET_CHART\", chart })`. This component wires the\n * `<KLineChart>` renderer from `react-klinecharts` to that bridge for you —\n * building the data loader, forwarding symbol/period/theme/locale/timezone\n * from provider state, bootstrapping the default indicators, and dispatching\n * `SET_CHART` on ready.\n *\n * It is the fastest path to a working chart. For full control (custom\n * lifecycle, a different renderer, or direct `klinecharts.init()`), render the\n * chart yourself and dispatch `SET_CHART` — see the README \"Renderer-agnostic\"\n * section.\n *\n * This entry point requires `react-klinecharts` as an optional peer\n * dependency. Install it explicitly when you import from\n * `react-klinecharts-ui/chart`.\n */\nexport function ChartCanvas({\n  className,\n  children,\n  options,\n  styles,\n}: ChartCanvasProps): ReactNode {\n  const { state, dispatch, datafeed } = useKlinechartsUI();\n\n  const dataLoader = useMemo(\n    () => createDataLoader(datafeed, dispatch),\n    [datafeed, dispatch],\n  );\n\n  // Keep the latest default indicator lists in refs so `handleReady` stays\n  // stable (only depends on `dispatch`) yet reads current values when the\n  // chart finishes initializing.\n  const mainIndicatorsRef = useRef(state.mainIndicators);\n  const subIndicatorsRef = useRef(state.subIndicators);\n  useEffect(() => {\n    mainIndicatorsRef.current = state.mainIndicators;\n    subIndicatorsRef.current = state.subIndicators;\n  }, [state.mainIndicators, state.subIndicators]);\n\n  const handleReady = useCallback(\n    (chart: Chart) => {\n      // The bridge: register the chart instance so every hook can drive it.\n      dispatch({ type: \"SET_CHART\", chart });\n\n      // Bootstrap the provider's default indicators onto the fresh chart,\n      // mirroring the canonical pattern in examples/ChartView.tsx.\n      mainIndicatorsRef.current.forEach((name) => {\n        chart.createIndicator(\n          { name, id: `main_${name}` },\n          { isStack: true, pane: { id: \"candle_pane\" } },\n        );\n      });\n\n      const subUpdates: Record<string, string> = {};\n      Object.keys(subIndicatorsRef.current).forEach((name) => {\n        const id = `sub_${name}`;\n        chart.createIndicator({ name, id });\n        const ind = chart.getIndicators({ id })[0];\n        if (ind?.paneId) subUpdates[name] = ind.paneId;\n      });\n      if (Object.keys(subUpdates).length > 0) {\n        dispatch({\n          type: \"SET_SUB_INDICATORS\",\n          indicators: { ...subIndicatorsRef.current, ...subUpdates },\n        });\n      }\n    },\n    [dispatch],\n  );\n\n  return (\n    <KLineChart\n      className={className}\n      options={options}\n      styles={styles ?? state.theme}\n      dataLoader={dataLoader}\n      symbol={state.symbol ?? undefined}\n      period={state.period}\n      locale={state.locale}\n      timezone={state.timezone}\n      onReady={handleReady}\n    >\n      {children}\n    </KLineChart>\n  );\n}\n"]}

package/dist/chart.d.cts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+import { Options, DeepPartial, Styles } from 'klinecharts';
+
+interface ChartCanvasProps {
+    /** className applied to the chart container div. */
+    className?: string;
+    /**
+     * Optional children rendered inside `<KLineChart>` (use the `<Widget>`
+     * component from `react-klinecharts` to portal React into chart DOM layers).
+     */
+    children?: ReactNode;
+    /**
+     * Chart initialization options, applied once on mount. Forwarded to
+     * `<KLineChart>` as the `options` prop.
+     */
+    options?: Options;
+    /**
+     * Styles override applied on mount and whenever it changes. Forwarded to
+     * `<KLineChart>` as the `styles` prop.
+     */
+    styles?: string | DeepPartial<Styles>;
+}
+/**
+ * Thin renderer wrapper for `react-klinecharts-ui`.
+ *
+ * `react-klinecharts-ui` is **headless / renderer-agnostic**: it only needs a
+ * klinecharts `Chart` instance to be registered via
+ * `dispatch({ type: "SET_CHART", chart })`. This component wires the
+ * `<KLineChart>` renderer from `react-klinecharts` to that bridge for you —
+ * building the data loader, forwarding symbol/period/theme/locale/timezone
+ * from provider state, bootstrapping the default indicators, and dispatching
+ * `SET_CHART` on ready.
+ *
+ * It is the fastest path to a working chart. For full control (custom
+ * lifecycle, a different renderer, or direct `klinecharts.init()`), render the
+ * chart yourself and dispatch `SET_CHART` — see the README "Renderer-agnostic"
+ * section.
+ *
+ * This entry point requires `react-klinecharts` as an optional peer
+ * dependency. Install it explicitly when you import from
+ * `react-klinecharts-ui/chart`.
+ */
+declare function ChartCanvas({ className, children, options, styles, }: ChartCanvasProps): ReactNode;
+
+export { ChartCanvas, type ChartCanvasProps };

package/dist/chart.d.ts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+import { Options, DeepPartial, Styles } from 'klinecharts';
+
+interface ChartCanvasProps {
+    /** className applied to the chart container div. */
+    className?: string;
+    /**
+     * Optional children rendered inside `<KLineChart>` (use the `<Widget>`
+     * component from `react-klinecharts` to portal React into chart DOM layers).
+     */
+    children?: ReactNode;
+    /**
+     * Chart initialization options, applied once on mount. Forwarded to
+     * `<KLineChart>` as the `options` prop.
+     */
+    options?: Options;
+    /**
+     * Styles override applied on mount and whenever it changes. Forwarded to
+     * `<KLineChart>` as the `styles` prop.
+     */
+    styles?: string | DeepPartial<Styles>;
+}
+/**
+ * Thin renderer wrapper for `react-klinecharts-ui`.
+ *
+ * `react-klinecharts-ui` is **headless / renderer-agnostic**: it only needs a
+ * klinecharts `Chart` instance to be registered via
+ * `dispatch({ type: "SET_CHART", chart })`. This component wires the
+ * `<KLineChart>` renderer from `react-klinecharts` to that bridge for you —
+ * building the data loader, forwarding symbol/period/theme/locale/timezone
+ * from provider state, bootstrapping the default indicators, and dispatching
+ * `SET_CHART` on ready.
+ *
+ * It is the fastest path to a working chart. For full control (custom
+ * lifecycle, a different renderer, or direct `klinecharts.init()`), render the
+ * chart yourself and dispatch `SET_CHART` — see the README "Renderer-agnostic"
+ * section.
+ *
+ * This entry point requires `react-klinecharts` as an optional peer
+ * dependency. Install it explicitly when you import from
+ * `react-klinecharts-ui/chart`.
+ */
+declare function ChartCanvas({ className, children, options, styles, }: ChartCanvasProps): ReactNode;
+
+export { ChartCanvas, type ChartCanvasProps };

package/dist/chart.js

@@ -0,0 +1,68 @@
+import { useKlinechartsUI, createDataLoader } from './chunk-O7E57I66.js';
+import './chunk-PZ5AY32C.js';
+import { useMemo, useRef, useEffect, useCallback } from 'react';
+import { KLineChart } from 'react-klinecharts';
+import { jsx } from 'react/jsx-runtime';
+
+function ChartCanvas({
+  className,
+  children,
+  options,
+  styles
+}) {
+  const { state, dispatch, datafeed } = useKlinechartsUI();
+  const dataLoader = useMemo(
+    () => createDataLoader(datafeed, dispatch),
+    [datafeed, dispatch]
+  );
+  const mainIndicatorsRef = useRef(state.mainIndicators);
+  const subIndicatorsRef = useRef(state.subIndicators);
+  useEffect(() => {
+    mainIndicatorsRef.current = state.mainIndicators;
+    subIndicatorsRef.current = state.subIndicators;
+  }, [state.mainIndicators, state.subIndicators]);
+  const handleReady = useCallback(
+    (chart) => {
+      dispatch({ type: "SET_CHART", chart });
+      mainIndicatorsRef.current.forEach((name) => {
+        chart.createIndicator(
+          { name, id: `main_${name}` },
+          { isStack: true, pane: { id: "candle_pane" } }
+        );
+      });
+      const subUpdates = {};
+      Object.keys(subIndicatorsRef.current).forEach((name) => {
+        const id = `sub_${name}`;
+        chart.createIndicator({ name, id });
+        const ind = chart.getIndicators({ id })[0];
+        if (ind?.paneId) subUpdates[name] = ind.paneId;
+      });
+      if (Object.keys(subUpdates).length > 0) {
+        dispatch({
+          type: "SET_SUB_INDICATORS",
+          indicators: { ...subIndicatorsRef.current, ...subUpdates }
+        });
+      }
+    },
+    [dispatch]
+  );
+  return /* @__PURE__ */ jsx(
+    KLineChart,
+    {
+      className,
+      options,
+      styles: styles ?? state.theme,
+      dataLoader,
+      symbol: state.symbol ?? void 0,
+      period: state.period,
+      locale: state.locale,
+      timezone: state.timezone,
+      onReady: handleReady,
+      children
+    }
+  );
+}
+
+export { ChartCanvas };
+//# sourceMappingURL=chart.js.map
+//# sourceMappingURL=chart.js.map

package/dist/chart.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/chart/ChartCanvas.tsx"],"names":[],"mappings":";;;;;;AAsDO,SAAS,WAAA,CAAY;AAAA,EAC1B,SAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAA,EAAgC;AAC9B,EAAA,MAAM,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,KAAa,gBAAA,EAAiB;AAEvD,EAAA,MAAM,UAAA,GAAa,OAAA;AAAA,IACjB,MAAM,gBAAA,CAAiB,QAAA,EAAU,QAAQ,CAAA;AAAA,IACzC,CAAC,UAAU,QAAQ;AAAA,GACrB;AAKA,EAAA,MAAM,iBAAA,GAAoB,MAAA,CAAO,KAAA,CAAM,cAAc,CAAA;AACrD,EAAA,MAAM,gBAAA,GAAmB,MAAA,CAAO,KAAA,CAAM,aAAa,CAAA;AACnD,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,iBAAA,CAAkB,UAAU,KAAA,CAAM,cAAA;AAClC,IAAA,gBAAA,CAAiB,UAAU,KAAA,CAAM,aAAA;AAAA,EACnC,GAAG,CAAC,KAAA,CAAM,cAAA,EAAgB,KAAA,CAAM,aAAa,CAAC,CAAA;AAE9C,EAAA,MAAM,WAAA,GAAc,WAAA;AAAA,IAClB,CAAC,KAAA,KAAiB;AAEhB,MAAA,QAAA,CAAS,EAAE,IAAA,EAAM,WAAA,EAAa,KAAA,EAAO,CAAA;AAIrC,MAAA,iBAAA,CAAkB,OAAA,CAAQ,OAAA,CAAQ,CAAC,IAAA,KAAS;AAC1C,QAAA,KAAA,CAAM,eAAA;AAAA,UACJ,EAAE,IAAA,EAAM,EAAA,EAAI,CAAA,KAAA,EAAQ,IAAI,CAAA,CAAA,EAAG;AAAA,UAC3B,EAAE,OAAA,EAAS,IAAA,EAAM,MAAM,EAAE,EAAA,EAAI,eAAc;AAAE,SAC/C;AAAA,MACF,CAAC,CAAA;AAED,MAAA,MAAM,aAAqC,EAAC;AAC5C,MAAA,MAAA,CAAO,KAAK,gBAAA,CAAiB,OAAO,CAAA,CAAE,OAAA,CAAQ,CAAC,IAAA,KAAS;AACtD,QAAA,MAAM,EAAA,GAAK,OAAO,IAAI,CAAA,CAAA;AACtB,QAAA,KAAA,CAAM,eAAA,CAAgB,EAAE,IAAA,EAAM,EAAA,EAAI,CAAA;AAClC,QAAA,MAAM,MAAM,KAAA,CAAM,aAAA,CAAc,EAAE,EAAA,EAAI,EAAE,CAAC,CAAA;AACzC,QAAA,IAAI,GAAA,EAAK,MAAA,EAAQ,UAAA,CAAW,IAAI,IAAI,GAAA,CAAI,MAAA;AAAA,MAC1C,CAAC,CAAA;AACD,MAAA,IAAI,MAAA,CAAO,IAAA,CAAK,UAAU,CAAA,CAAE,SAAS,CAAA,EAAG;AACtC,QAAA,QAAA,CAAS;AAAA,UACP,IAAA,EAAM,oBAAA;AAAA,UACN,YAAY,EAAE,GAAG,gBAAA,CAAiB,OAAA,EAAS,GAAG,UAAA;AAAW,SAC1D,CAAA;AAAA,MACH;AAAA,IACF,CAAA;AAAA,IACA,CAAC,QAAQ;AAAA,GACX;AAEA,EAAA,uBACE,GAAA;AAAA,IAAC,UAAA;AAAA,IAAA;AAAA,MACC,SAAA;AAAA,MACA,OAAA;AAAA,MACA,MAAA,EAAQ,UAAU,KAAA,CAAM,KAAA;AAAA,MACxB,UAAA;AAAA,MACA,MAAA,EAAQ,MAAM,MAAA,IAAU,MAAA;AAAA,MACxB,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,UAAU,KAAA,CAAM,QAAA;AAAA,MAChB,OAAA,EAAS,WAAA;AAAA,MAER;AAAA;AAAA,GACH;AAEJ","file":"chart.js","sourcesContent":["import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  type ReactNode,\n} from \"react\";\nimport { KLineChart } from \"react-klinecharts\";\nimport type { Chart, Options, DeepPartial, Styles } from \"klinecharts\";\nimport {\n  useKlinechartsUI,\n} from \"../provider/ChartTerminalContext\";\nimport { createDataLoader } from \"../utils/createDataLoader\";\n\nexport interface ChartCanvasProps {\n  /** className applied to the chart container div. */\n  className?: string;\n  /**\n   * Optional children rendered inside `<KLineChart>` (use the `<Widget>`\n   * component from `react-klinecharts` to portal React into chart DOM layers).\n   */\n  children?: ReactNode;\n  /**\n   * Chart initialization options, applied once on mount. Forwarded to\n   * `<KLineChart>` as the `options` prop.\n   */\n  options?: Options;\n  /**\n   * Styles override applied on mount and whenever it changes. Forwarded to\n   * `<KLineChart>` as the `styles` prop.\n   */\n  styles?: string | DeepPartial<Styles>;\n}\n\n/**\n * Thin renderer wrapper for `react-klinecharts-ui`.\n *\n * `react-klinecharts-ui` is **headless / renderer-agnostic**: it only needs a\n * klinecharts `Chart` instance to be registered via\n * `dispatch({ type: \"SET_CHART\", chart })`. This component wires the\n * `<KLineChart>` renderer from `react-klinecharts` to that bridge for you —\n * building the data loader, forwarding symbol/period/theme/locale/timezone\n * from provider state, bootstrapping the default indicators, and dispatching\n * `SET_CHART` on ready.\n *\n * It is the fastest path to a working chart. For full control (custom\n * lifecycle, a different renderer, or direct `klinecharts.init()`), render the\n * chart yourself and dispatch `SET_CHART` — see the README \"Renderer-agnostic\"\n * section.\n *\n * This entry point requires `react-klinecharts` as an optional peer\n * dependency. Install it explicitly when you import from\n * `react-klinecharts-ui/chart`.\n */\nexport function ChartCanvas({\n  className,\n  children,\n  options,\n  styles,\n}: ChartCanvasProps): ReactNode {\n  const { state, dispatch, datafeed } = useKlinechartsUI();\n\n  const dataLoader = useMemo(\n    () => createDataLoader(datafeed, dispatch),\n    [datafeed, dispatch],\n  );\n\n  // Keep the latest default indicator lists in refs so `handleReady` stays\n  // stable (only depends on `dispatch`) yet reads current values when the\n  // chart finishes initializing.\n  const mainIndicatorsRef = useRef(state.mainIndicators);\n  const subIndicatorsRef = useRef(state.subIndicators);\n  useEffect(() => {\n    mainIndicatorsRef.current = state.mainIndicators;\n    subIndicatorsRef.current = state.subIndicators;\n  }, [state.mainIndicators, state.subIndicators]);\n\n  const handleReady = useCallback(\n    (chart: Chart) => {\n      // The bridge: register the chart instance so every hook can drive it.\n      dispatch({ type: \"SET_CHART\", chart });\n\n      // Bootstrap the provider's default indicators onto the fresh chart,\n      // mirroring the canonical pattern in examples/ChartView.tsx.\n      mainIndicatorsRef.current.forEach((name) => {\n        chart.createIndicator(\n          { name, id: `main_${name}` },\n          { isStack: true, pane: { id: \"candle_pane\" } },\n        );\n      });\n\n      const subUpdates: Record<string, string> = {};\n      Object.keys(subIndicatorsRef.current).forEach((name) => {\n        const id = `sub_${name}`;\n        chart.createIndicator({ name, id });\n        const ind = chart.getIndicators({ id })[0];\n        if (ind?.paneId) subUpdates[name] = ind.paneId;\n      });\n      if (Object.keys(subUpdates).length > 0) {\n        dispatch({\n          type: \"SET_SUB_INDICATORS\",\n          indicators: { ...subIndicatorsRef.current, ...subUpdates },\n        });\n      }\n    },\n    [dispatch],\n  );\n\n  return (\n    <KLineChart\n      className={className}\n      options={options}\n      styles={styles ?? state.theme}\n      dataLoader={dataLoader}\n      symbol={state.symbol ?? undefined}\n      period={state.period}\n      locale={state.locale}\n      timezone={state.timezone}\n      onReady={handleReady}\n    >\n      {children}\n    </KLineChart>\n  );\n}\n"]}

package/dist/chunk-F24D6PWY.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+var react = require('react');
+
+// src/provider/ChartTerminalContext.ts
+var KlinechartsUIStateContext = react.createContext(null);
+var KlinechartsUIDispatchContext = react.createContext(null);
+function useKlinechartsUIDispatch() {
+  const ctx = react.useContext(KlinechartsUIDispatchContext);
+  if (!ctx) {
+    throw new Error(
+      "useKlinechartsUI must be used within a <KlinechartsUIProvider>"
+    );
+  }
+  return ctx;
+}
+function useKlinechartsUI() {
+  const state = react.useContext(KlinechartsUIStateContext);
+  const dispatch = react.useContext(KlinechartsUIDispatchContext);
+  if (!state || !dispatch) {
+    throw new Error(
+      "useKlinechartsUI must be used within a <KlinechartsUIProvider>"
+    );
+  }
+  return { state, ...dispatch };
+}
+
+// src/utils/createDataLoader.ts
+function createDataLoader(datafeed, dispatch) {
+  let oldestTimestamp = null;
+  let currentGen = 0;
+  return {
+    getBars: async (params) => {
+      try {
+        dispatch({ type: "SET_LOADING", isLoading: true });
+        if (params.type === "init") {
+          oldestTimestamp = null;
+          const gen = ++currentGen;
+          const data = await datafeed.getHistoryKLineData(
+            params.symbol,
+            { ...params.period, label: "" },
+            0,
+            Date.now()
+          );
+          if (gen !== currentGen) return;
+          if (data.length > 0) {
+            oldestTimestamp = data[0].timestamp;
+          }
+          params.callback(data, {
+            forward: data.length > 0,
+            backward: false
+          });
+        } else if (params.type === "forward" && oldestTimestamp !== null) {
+          const gen = currentGen;
+          const data = await datafeed.getHistoryKLineData(
+            params.symbol,
+            { ...params.period, label: "" },
+            0,
+            oldestTimestamp - 1
+          );
+          if (gen !== currentGen) return;
+          if (data.length > 0) {
+            oldestTimestamp = data[0].timestamp;
+          }
+          params.callback(data, {
+            forward: data.length > 0,
+            backward: false
+          });
+        } else if (params.type === "backward") {
+          params.callback([], { forward: false, backward: false });
+        }
+      } catch (error) {
+        console.error("Failed to load chart data:", error);
+        params.callback([], { forward: false, backward: false });
+      } finally {
+        dispatch({ type: "SET_LOADING", isLoading: false });
+      }
+    },
+    subscribeBar: (params) => {
+      datafeed.subscribe(
+        params.symbol,
+        { ...params.period, label: "" },
+        (klineData) => params.callback(klineData)
+      );
+    },
+    unsubscribeBar: (params) => {
+      datafeed.unsubscribe(params.symbol, { ...params.period, label: "" });
+    }
+  };
+}
+
+exports.KlinechartsUIDispatchContext = KlinechartsUIDispatchContext;
+exports.KlinechartsUIStateContext = KlinechartsUIStateContext;
+exports.createDataLoader = createDataLoader;
+exports.useKlinechartsUI = useKlinechartsUI;
+exports.useKlinechartsUIDispatch = useKlinechartsUIDispatch;
+//# sourceMappingURL=chunk-F24D6PWY.cjs.map
+//# sourceMappingURL=chunk-F24D6PWY.cjs.map

package/dist/chunk-F24D6PWY.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider/ChartTerminalContext.ts","../src/utils/createDataLoader.ts"],"names":["createContext","useContext"],"mappings":";;;;;AAOO,IAAM,yBAAA,GACXA,oBAAyC,IAAI;AAExC,IAAM,4BAAA,GACXA,oBAAiD,IAAI;AAOhD,SAAS,wBAAA,GAAuD;AACrE,EAAA,MAAM,GAAA,GAAMC,iBAAW,4BAA4B,CAAA;AACnD,EAAA,IAAI,CAAC,GAAA,EAAK;AACR,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT;AAMO,SAAS,gBAAA,GAA8C;AAC5D,EAAA,MAAM,KAAA,GAAQA,iBAAW,yBAAyB,CAAA;AAClD,EAAA,MAAM,QAAA,GAAWA,iBAAW,4BAA4B,CAAA;AACxD,EAAA,IAAI,CAAC,KAAA,IAAS,CAAC,QAAA,EAAU;AACvB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACA,EAAA,OAAO,EAAE,KAAA,EAAO,GAAG,QAAA,EAAS;AAC9B;;;AC3BO,SAAS,gBAAA,CACd,UACA,QAAA,EACY;AACZ,EAAA,IAAI,eAAA,GAAiC,IAAA;AAGrC,EAAA,IAAI,UAAA,GAAa,CAAA;AAEjB,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,OAAO,MAAA,KAAW;AACzB,MAAA,IAAI;AACF,QAAA,QAAA,CAAS,EAAE,IAAA,EAAM,aAAA,EAAe,SAAA,EAAW,MAAM,CAAA;AAEjD,QAAA,IAAI,MAAA,CAAO,SAAS,MAAA,EAAQ;AAC1B,UAAA,eAAA,GAAkB,IAAA;AAClB,UAAA,MAAM,MAAM,EAAE,UAAA;AACd,UAAA,MAAM,IAAA,GAAO,MAAM,QAAA,CAAS,mBAAA;AAAA,YAC1B,MAAA,CAAO,MAAA;AAAA,YACP,EAAE,GAAG,MAAA,CAAO,MAAA,EAAQ,OAAO,EAAA,EAAG;AAAA,YAC9B,CAAA;AAAA,YACA,KAAK,GAAA;AAAI,WACX;AACA,UAAA,IAAI,QAAQ,UAAA,EAAY;AACxB,UAAA,IAAI,IAAA,CAAK,SAAS,CAAA,EAAG;AACnB,YAAA,eAAA,GAAkB,IAAA,CAAK,CAAC,CAAA,CAAE,SAAA;AAAA,UAC5B;AACA,UAAA,MAAA,CAAO,SAAS,IAAA,EAAqB;AAAA,YACnC,OAAA,EAAS,KAAK,MAAA,GAAS,CAAA;AAAA,YACvB,QAAA,EAAU;AAAA,WACX,CAAA;AAAA,QACH,CAAA,MAAA,IAAW,MAAA,CAAO,IAAA,KAAS,SAAA,IAAa,oBAAoB,IAAA,EAAM;AAChE,UAAA,MAAM,GAAA,GAAM,UAAA;AACZ,UAAA,MAAM,IAAA,GAAO,MAAM,QAAA,CAAS,mBAAA;AAAA,YAC1B,MAAA,CAAO,MAAA;AAAA,YACP,EAAE,GAAG,MAAA,CAAO,MAAA,EAAQ,OAAO,EAAA,EAAG;AAAA,YAC9B,CAAA;AAAA,YACA,eAAA,GAAkB;AAAA,WACpB;AACA,UAAA,IAAI,QAAQ,UAAA,EAAY;AACxB,UAAA,IAAI,IAAA,CAAK,SAAS,CAAA,EAAG;AACnB,YAAA,eAAA,GAAkB,IAAA,CAAK,CAAC,CAAA,CAAE,SAAA;AAAA,UAC5B;AACA,UAAA,MAAA,CAAO,SAAS,IAAA,EAAqB;AAAA,YACnC,OAAA,EAAS,KAAK,MAAA,GAAS,CAAA;AAAA,YACvB,QAAA,EAAU;AAAA,WACX,CAAA;AAAA,QACH,CAAA,MAAA,IAAW,MAAA,CAAO,IAAA,KAAS,UAAA,EAAY;AAGrC,UAAA,MAAA,CAAO,QAAA,CAAS,EAAC,EAAG,EAAE,SAAS,KAAA,EAAO,QAAA,EAAU,OAAO,CAAA;AAAA,QACzD;AAAA,MACF,SAAS,KAAA,EAAO;AACd,QAAA,OAAA,CAAQ,KAAA,CAAM,8BAA8B,KAAK,CAAA;AACjD,QAAA,MAAA,CAAO,QAAA,CAAS,EAAC,EAAG,EAAE,SAAS,KAAA,EAAO,QAAA,EAAU,OAAO,CAAA;AAAA,MACzD,CAAA,SAAE;AACA,QAAA,QAAA,CAAS,EAAE,IAAA,EAAM,aAAA,EAAe,SAAA,EAAW,OAAO,CAAA;AAAA,MACpD;AAAA,IACF,CAAA;AAAA,IACA,YAAA,EAAc,CAAC,MAAA,KAAW;AACxB,MAAA,QAAA,CAAS,SAAA;AAAA,QACP,MAAA,CAAO,MAAA;AAAA,QACP,EAAE,GAAG,MAAA,CAAO,MAAA,EAAQ,OAAO,EAAA,EAAG;AAAA,QAC9B,CAAC,SAAA,KAAc,MAAA,CAAO,QAAA,CAAS,SAAsB;AAAA,OACvD;AAAA,IACF,CAAA;AAAA,IACA,cAAA,EAAgB,CAAC,MAAA,KAAW;AAC1B,MAAA,QAAA,CAAS,WAAA,CAAY,OAAO,MAAA,EAAQ,EAAE,GAAG,MAAA,CAAO,MAAA,EAAQ,KAAA,EAAO,EAAA,EAAI,CAAA;AAAA,IACrE;AAAA,GACF;AACF","file":"chunk-F24D6PWY.cjs","sourcesContent":["import { createContext, useContext } from \"react\";\nimport type {\n  KlinechartsUIState,\n  KlinechartsUIContextValue,\n  KlinechartsUIDispatchValue,\n} from \"./types\";\n\nexport const KlinechartsUIStateContext =\n  createContext<KlinechartsUIState | null>(null);\n\nexport const KlinechartsUIDispatchContext =\n  createContext<KlinechartsUIDispatchValue | null>(null);\n\n/**\n * @internal\n * Reads only the stable dispatch slice. Hooks that use this won't re-render\n * when chart state changes (e.g. symbol, period, isLoading).\n */\nexport function useKlinechartsUIDispatch(): KlinechartsUIDispatchValue {\n  const ctx = useContext(KlinechartsUIDispatchContext);\n  if (!ctx) {\n    throw new Error(\n      \"useKlinechartsUI must be used within a <KlinechartsUIProvider>\"\n    );\n  }\n  return ctx;\n}\n\n/**\n * Primary hook — returns the full combined context value.\n * For performance-sensitive cases, prefer the two split hooks internally.\n */\nexport function useKlinechartsUI(): KlinechartsUIContextValue {\n  const state = useContext(KlinechartsUIStateContext);\n  const dispatch = useContext(KlinechartsUIDispatchContext);\n  if (!state || !dispatch) {\n    throw new Error(\n      \"useKlinechartsUI must be used within a <KlinechartsUIProvider>\"\n    );\n  }\n  return { state, ...dispatch };\n}\n","import type { Dispatch } from \"react\";\nimport type { DataLoader, KLineData } from \"klinecharts\";\nimport type { Datafeed, KlinechartsUIAction } from \"../provider/types\";\n\n/**\n * Creates a klinecharts DataLoader from a Datafeed instance.\n * This bridges the react-klinecharts-ui Datafeed interface to the\n * klinecharts native DataLoader format used by KLineChart component.\n *\n * In klinecharts terminology:\n * - \"init\" = initial data load\n * - \"forward\" = load older data (user scrolled left into history)\n * - \"backward\" = load newer data (user scrolled right)\n */\nexport function createDataLoader(\n  datafeed: Datafeed,\n  dispatch: Dispatch<KlinechartsUIAction>,\n): DataLoader {\n  let oldestTimestamp: number | null = null;\n  // Incremented on every \"init\" request. Forward requests capture the value at\n  // their start and bail out if a newer init has begun while they were in-flight.\n  let currentGen = 0;\n\n  return {\n    getBars: async (params) => {\n      try {\n        dispatch({ type: \"SET_LOADING\", isLoading: true });\n\n        if (params.type === \"init\") {\n          oldestTimestamp = null;\n          const gen = ++currentGen;\n          const data = await datafeed.getHistoryKLineData(\n            params.symbol,\n            { ...params.period, label: \"\" },\n            0,\n            Date.now(),\n          );\n          if (gen !== currentGen) return; // newer init started — discard stale result\n          if (data.length > 0) {\n            oldestTimestamp = data[0].timestamp;\n          }\n          params.callback(data as KLineData[], {\n            forward: data.length > 0,\n            backward: false,\n          });\n        } else if (params.type === \"forward\" && oldestTimestamp !== null) {\n          const gen = currentGen;\n          const data = await datafeed.getHistoryKLineData(\n            params.symbol,\n            { ...params.period, label: \"\" },\n            0,\n            oldestTimestamp - 1,\n          );\n          if (gen !== currentGen) return; // init for new period started — discard\n          if (data.length > 0) {\n            oldestTimestamp = data[0].timestamp;\n          }\n          params.callback(data as KLineData[], {\n            forward: data.length > 0,\n            backward: false,\n          });\n        } else if (params.type === \"backward\") {\n          // Backward pagination (loading data newer than what we have) is generally\n          // not needed in typical terminal usage because we subscribe via ws for real-time.\n          params.callback([], { forward: false, backward: false });\n        }\n      } catch (error) {\n        console.error(\"Failed to load chart data:\", error);\n        params.callback([], { forward: false, backward: false });\n      } finally {\n        dispatch({ type: \"SET_LOADING\", isLoading: false });\n      }\n    },\n    subscribeBar: (params) => {\n      datafeed.subscribe(\n        params.symbol,\n        { ...params.period, label: \"\" },\n        (klineData) => params.callback(klineData as KLineData),\n      );\n    },\n    unsubscribeBar: (params) => {\n      datafeed.unsubscribe(params.symbol, { ...params.period, label: \"\" });\n    },\n  };\n}\n"]}