react-klinecharts-ui 1.0.0 → 1.2.0

package/README.md

@@ -69,6 +69,17 @@ pnpm add react-klinecharts-ui 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
@@ -575,6 +750,7 @@ const {
   isLocked,
   isVisible,
   autoRetrigger,
+  overlays,
   selectTool,
   clearActiveTool,
   setMagnetMode,
@@ -582,24 +758,31 @@ const {
   toggleVisibility,
   removeAllDrawings,
   setAutoRetrigger,
+  removeDrawing,
+  setDrawingVisible,
+  setDrawingLocked,
 } = useDrawingTools();
 ```
 
-| Field/Method          | Type                             | Description                                             |
-| --------------------- | -------------------------------- | ------------------------------------------------------- |
-| `categories`          | `DrawingCategoryItem[]`          | Tool categories with nested tools                       |
-| `activeTool`          | `string \| null`                 | Name of the last selected tool                          |
-| `magnetMode`          | `"normal" \| "weak" \| "strong"` | Snap-to-OHLC mode                                       |
-| `isLocked`            | `boolean`                        | Whether all drawings are locked                         |
-| `isVisible`           | `boolean`                        | Whether all drawings are visible                        |
-| `autoRetrigger`       | `boolean`                        | Re-arm the tool after finishing a shape (default `true`) |
-| `selectTool(name)`    | —                                | Start drawing via `chart.createOverlay`                 |
-| `clearActiveTool()`   | —                                | Deselect tool (local state only)                        |
-| `setMagnetMode(mode)` | —                                | Change magnet mode for all existing and future drawings |
-| `toggleLock()`        | —                                | Toggle lock on all drawings                             |
-| `toggleVisibility()`  | —                                | Show/hide all drawings                                  |
-| `removeAllDrawings()` | —                                | Remove all drawings in the `drawing_tools` group        |
-| `setAutoRetrigger(enabled)` | —                          | Enable/disable auto re-arming                           |
+| Field/Method             | Type                             | Description                                             |
+| ------------------------ | -------------------------------- | ------------------------------------------------------- |
+| `categories`             | `DrawingCategoryItem[]`          | Tool categories with nested tools                       |
+| `activeTool`             | `string \| null`                 | Name of the last selected tool                          |
+| `magnetMode`             | `"normal" \| "weak" \| "strong"` | Snap-to-OHLC mode                                       |
+| `isLocked`               | `boolean`                        | Whether all drawings are locked                         |
+| `isVisible`              | `boolean`                        | Whether all drawings are visible                        |
+| `autoRetrigger`          | `boolean`                        | Re-arm the tool after finishing a shape (default `true`) |
+| `overlays`               | `DrawingOverlayInfo[]`           | Reactive list of drawings in the `drawing_tools` group |
+| `selectTool(name)`       | —                                | Start drawing via `chart.createOverlay`                 |
+| `clearActiveTool()`      | —                                | Deselect tool (local state only)                        |
+| `setMagnetMode(mode)`    | —                                | Change magnet mode for all existing and future drawings |
+| `toggleLock()`           | —                                | Toggle lock on all drawings                             |
+| `toggleVisibility()`     | —                                | Show/hide all drawings                                  |
+| `removeAllDrawings()`    | —                                | Remove all drawings in the `drawing_tools` group        |
+| `setAutoRetrigger(enabled)` | —                            | Enable/disable auto re-arming                           |
+| `removeDrawing(id)`      | —                                | Remove a single drawing by id                           |
+| `setDrawingVisible(id, visible)` | —                        | Show/hide a single drawing                              |
+| `setDrawingLocked(id, locked)` | —                          | Lock/unlock a single drawing                            |
 
 ```typescript
 interface DrawingToolItem {
@@ -611,8 +794,39 @@ interface DrawingCategoryItem {
   key: string; // "singleLine" | "moreLine" | "polygon" | "fibonacci" | "wave"
   tools: DrawingToolItem[];
 }
+
+interface DrawingOverlayInfo {
+  id: string;       // Stable id from klinecharts (chart.getOverlays()[].id)
+  name: string;     // Overlay name, e.g. "segment", "fibonacciLine", "arrow"
+  paneId: string;   // Pane id where the drawing lives
+  locked: boolean;  // Current lock state
+  visible: boolean; // Current visibility
+}
 ```
 
+#### Per-drawing management
+
+`overlays` is a **reactive** snapshot of the drawings in the `drawing_tools` group. It updates when a drawing is created (via `selectTool` + finishing a shape on the canvas), removed, or has its `locked`/`visible` properties changed — both through the per-drawing operations above and through the batch operations (`toggleLock`, `toggleVisibility`, `removeAllDrawings`).
+
+Because klinecharts v10 has no overlay change events, the hook also runs a 1s polling fallback so changes made **outside** the hook (e.g. the user pressing <kbd>Delete</kbd> via klinecharts, or undo/redo) are still reflected.
+
+```typescript
+// Build an Object Tree panel from `overlays`
+const { overlays, removeDrawing, setDrawingVisible, setDrawingLocked } = useDrawingTools();
+// overlays.map((o) => (
+//   <Row
+//     key={o.id}
+//     label={drawingLabel(o.name)}   // "segment" -> "segment" locale key
+//     visible={o.visible}
+//     locked={o.locked}
+//     onToggleVis={() => setDrawingVisible(o.id, !o.visible)}
+//     onDel={() => removeDrawing(o.id)}
+//   />
+// ));
+```
+
+`drawingLabel(name)` is an exported helper that maps a klinecharts overlay name to its `localeKey` using `DRAWING_CATEGORIES` (falls back to the name itself when the tool is unknown), so consumers don't have to duplicate the category table.
+
 **Categories and tools:**
 
 | Category (`key`) | Tools                                                                                                                                                                  |
@@ -2084,4 +2298,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