react-klinecharts-ui 1.1.0 → 1.2.0

package/README.md

@@ -750,6 +750,7 @@ const {
   isLocked,
   isVisible,
   autoRetrigger,
+  overlays,
   selectTool,
   clearActiveTool,
   setMagnetMode,
@@ -757,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 {
@@ -786,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                                                                                                                                                                  |

package/dist/index.cjs

@@ -1358,6 +1358,25 @@ var DRAWING_CATEGORIES = [
 
 // src/hooks/useDrawingTools.ts
 var DRAWING_GROUP_ID = "drawing_tools";
+var DRAWING_NAME_TO_LOCALE_KEY = new Map(
+  DRAWING_CATEGORIES.flatMap(
+    (cat) => cat.tools.map((tool) => [tool.name, tool.localeKey])
+  )
+);
+function drawingLabel(name) {
+  return DRAWING_NAME_TO_LOCALE_KEY.get(name) ?? name;
+}
+function overlaysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x.id !== y.id || x.name !== y.name || x.paneId !== y.paneId || x.locked !== y.locked || x.visible !== y.visible) {
+      return false;
+    }
+  }
+  return true;
+}
 function useDrawingTools() {
   const { state } = chunkF24D6PWY_cjs.useKlinechartsUI();
   const { undoRedoListenerRef } = chunkF24D6PWY_cjs.useKlinechartsUIDispatch();
@@ -1378,6 +1397,34 @@ function useDrawingTools() {
     isVisibleRef.current = isVisible;
     magnetModeRef.current = magnetMode;
   });
+  const [overlays2, setOverlays] = react.useState([]);
+  const refreshOverlays = react.useCallback(() => {
+    if (!state.chart) {
+      setOverlays((prev) => prev.length === 0 ? prev : []);
+      return;
+    }
+    const list = state.chart.getOverlays({ groupId: DRAWING_GROUP_ID });
+    const next = list.map((o) => ({
+      id: o.id,
+      name: o.name,
+      paneId: o.paneId,
+      locked: !!o.lock,
+      visible: o.visible !== false
+      // klinecharts default = true
+    }));
+    setOverlays((prev) => overlaysEqual(prev, next) ? prev : next);
+  }, [state.chart]);
+  const refreshOverlaysRef = react.useRef(() => {
+  });
+  react.useEffect(() => {
+    refreshOverlaysRef.current = refreshOverlays;
+  });
+  react.useEffect(() => {
+    if (!state.chart) return;
+    queueMicrotask(() => refreshOverlaysRef.current());
+    const interval = setInterval(() => refreshOverlaysRef.current(), 1e3);
+    return () => clearInterval(interval);
+  }, [state.chart, refreshOverlays]);
   const categories = react.useMemo(
     () => DRAWING_CATEGORIES.map((cat) => ({
       key: cat.key,
@@ -1413,6 +1460,7 @@ function useDrawingTools() {
               }
             }
           });
+          refreshOverlaysRef.current();
           if (autoRetriggerRef.current && activeToolRef.current === name) {
             requestAnimationFrame(() => {
               createOverlayForToolRef.current(name);
@@ -1439,49 +1487,52 @@ function useDrawingTools() {
   const setMagnetMode = react.useCallback(
     (mode) => {
       setMagnetModeState(mode);
-      const overlays2 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
-      if (overlays2) {
+      const overlays3 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
+      if (overlays3) {
         const overlayMode = mode === "strong" ? "strong_magnet" : mode === "weak" ? "weak_magnet" : "normal";
-        overlays2.forEach((overlay) => {
+        overlays3.forEach((overlay) => {
           state.chart?.overrideOverlay({
             id: overlay.id,
             mode: overlayMode
           });
         });
       }
+      refreshOverlaysRef.current();
     },
     [state.chart]
   );
   const toggleLock = react.useCallback(() => {
     const newLocked = !isLocked;
     setIsLocked(newLocked);
-    const overlays2 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
-    if (overlays2) {
-      overlays2.forEach((overlay) => {
+    const overlays3 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
+    if (overlays3) {
+      overlays3.forEach((overlay) => {
         state.chart?.overrideOverlay({
           id: overlay.id,
           lock: newLocked
         });
       });
     }
+    refreshOverlaysRef.current();
   }, [state.chart, isLocked]);
   const toggleVisibility = react.useCallback(() => {
     const newVisible = !isVisible;
     setIsVisible(newVisible);
-    const overlays2 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
-    if (overlays2) {
-      overlays2.forEach((overlay) => {
+    const overlays3 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
+    if (overlays3) {
+      overlays3.forEach((overlay) => {
         state.chart?.overrideOverlay({
           id: overlay.id,
           visible: newVisible
         });
       });
     }
+    refreshOverlaysRef.current();
   }, [state.chart, isVisible]);
   const removeAllDrawings = react.useCallback(() => {
-    const overlays2 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
-    if (overlays2 && overlays2.length > 0) {
-      const snapshot = overlays2.map((o) => ({
+    const overlays3 = state.chart?.getOverlays({ groupId: DRAWING_GROUP_ID });
+    if (overlays3 && overlays3.length > 0) {
+      const snapshot = overlays3.map((o) => ({
         name: o.name,
         id: o.id,
         points: o.points,
@@ -1495,7 +1546,29 @@ function useDrawingTools() {
     }
     state.chart?.removeOverlay({ groupId: DRAWING_GROUP_ID });
     setActiveTool(null);
+    refreshOverlaysRef.current();
   }, [state.chart, undoRedoListenerRef]);
+  const removeDrawing = react.useCallback(
+    (id) => {
+      state.chart?.removeOverlay({ id, groupId: DRAWING_GROUP_ID });
+      refreshOverlaysRef.current();
+    },
+    [state.chart]
+  );
+  const setDrawingVisible = react.useCallback(
+    (id, visible) => {
+      state.chart?.overrideOverlay({ id, visible });
+      refreshOverlaysRef.current();
+    },
+    [state.chart]
+  );
+  const setDrawingLocked = react.useCallback(
+    (id, locked) => {
+      state.chart?.overrideOverlay({ id, lock: locked });
+      refreshOverlaysRef.current();
+    },
+    [state.chart]
+  );
   return {
     categories,
     activeTool,
@@ -1503,13 +1576,17 @@ function useDrawingTools() {
     isLocked,
     isVisible,
     autoRetrigger,
+    overlays: overlays2,
     selectTool,
     clearActiveTool,
     setMagnetMode,
     toggleLock,
     toggleVisibility,
     removeAllDrawings,
-    setAutoRetrigger
+    setAutoRetrigger,
+    removeDrawing,
+    setDrawingVisible,
+    setDrawingLocked
   };
 }
 
@@ -3944,6 +4021,7 @@ exports.TOOLTIP_SHOW_RULES = TOOLTIP_SHOW_RULES;
 exports.WorkspaceProvider = WorkspaceProvider;
 exports.YAXIS_POSITIONS = YAXIS_POSITIONS;
 exports.createDefaultStorage = createDefaultStorage;
+exports.drawingLabel = drawingLabel;
 exports.resolveStorage = resolveStorage;
 exports.useAlerts = useAlerts;
 exports.useAnnotations = useAnnotations;