@funnest/charts 0.6.17 → 0.6.19

package/dist/chart.d.ts

@@ -99,6 +99,8 @@ export interface ChartEvents {
         canRedo: boolean;
     };
     comparesChange: CompareInfo[];
+    /** App rows in the legend (addLegendItem) were added, changed or removed. */
+    legendItemsChange: readonly LegendItem[];
     replayChange: ReplayStatus;
     /**
      * Right-click on the chart (mouse only). While anything listens, the browser's own menu is
@@ -123,6 +125,26 @@ export interface ChartPaneLayout {
     top: number;
     height: number;
 }
+/**
+ * A row an app puts in the chart's legend for something it draws itself (a liquidation map, an
+ * order-book heatmap, a line from its own data), so people can hide, configure or remove it
+ * right where they see the indicators.
+ */
+export interface LegendItemOptions {
+    name: string;
+    /** Starts shown. Default true. */
+    visible?: boolean;
+    /** 👁 hides / shows it: the app stops / resumes drawing. No eye without it. */
+    onToggle?(visible: boolean): void;
+    /** ⚙ opens the app's own settings for it. */
+    onSettings?(): void;
+    /** × turns it off (the app removes its drawing and this row). */
+    onRemove?(): void;
+}
+export interface LegendItem extends LegendItemOptions {
+    id: string;
+    visible: boolean;
+}
 export interface IndicatorLegendItem {
     id: string;
     type: IndicatorType;
@@ -168,6 +190,8 @@ export declare class Chart {
     private readonly cleanups;
     private readonly drawings;
     private readonly overlays;
+    private legendExtras;
+    private legendSeq;
     private readonly trading;
     private readonly tradingSync;
     private tooltipKey;
@@ -413,6 +437,18 @@ export declare class Chart {
     addOrderLine(options: OrderLineOptions): LineHandle<OrderLineOptions>;
     /** Price alert line (dotted, gray, "알림" label). Pass `onMove` to make it draggable and `onCancel` for an ×. */
     addAlertLine(options: AlertLineOptions): LineHandle<AlertLineOptions>;
+    /**
+     * Adds a row to the legend for something the app draws (see LegendItemOptions). `update()`
+     * changes its name or state; `remove()` takes the row away (the app removes its drawing).
+     */
+    addLegendItem(options: LegendItemOptions): {
+        update(patch: Partial<LegendItemOptions>): void;
+        remove(): void;
+    };
+    /** The app's legend rows, in the order they were added. */
+    get legendItems(): readonly LegendItem[];
+    /** The legend's 👁 on an app row: tells the app (onToggle) and remembers the state. */
+    setLegendItemVisible(id: string, visible: boolean): void;
     /**
      * Paints `overlay` on the price pane every frame (see ChartOverlay). `redraw()` asks for a
      * new frame after its data changed; `remove()` takes it off.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Chart, createChart, fallbackResolution } from './chart';
 export { CHART_THEMES, DEFAULT_CHART_SETTINGS, matchChartTheme, parseChartState } from './settings';
 export type { ChartSettings, ChartState, ChartThemeColors, ChartThemePreset } from './settings';
-export type { ChartContextMenu, ChartEvents, ChartLayout, ChartOptions, ChartPaneLayout, CompareInfo, IndicatorLegendItem, ReplayStatus } from './chart';
+export type { ChartContextMenu, ChartEvents, ChartLayout, ChartOptions, ChartPaneLayout, CompareInfo, IndicatorLegendItem, LegendItem, LegendItemOptions, ReplayStatus } from './chart';
 export type { PriceScaleMode } from './model/price-scale';
 export type { CrosshairInfo, PaneId } from './render/renderer';
 export type { Locale } from './model/time-format';

package/dist/index.js

@@ -2412,6 +2412,25 @@ function drawMain(layer, m) {
     }
   }
   if (f.settings.gridVertical) for (const tick of f.timeTicks) p.vLine(tick.x, 0, f.panesHeight, pal.grid);
+  const o = m.objects;
+  const rc = { painter: p, coords: o.coords, palette: pal };
+  const runOverlay = (overlay) => {
+    ctx.save();
+    try {
+      overlay.render(rc);
+    } catch (error) {
+      console.error("[fnc] overlay", error);
+    }
+    ctx.restore();
+  };
+  if (o.overlays.some((x) => x.layer === "below")) {
+    ctx.save();
+    ctx.beginPath();
+    ctx.rect(0, main.top, f.plotWidth, main.height);
+    ctx.clip();
+    for (const overlay of o.overlays) if (overlay.layer === "below") runOverlay(overlay);
+    ctx.restore();
+  }
   const hasBars = f.range.to >= f.range.from;
   if (hasBars) {
     ctx.save();
@@ -2451,17 +2470,7 @@ function drawMain(layer, m) {
   ctx.beginPath();
   ctx.rect(0, main.top, f.plotWidth, main.height);
   ctx.clip();
-  const o = m.objects;
-  const rc = { painter: p, coords: o.coords, palette: pal };
-  for (const overlay of o.overlays) {
-    ctx.save();
-    try {
-      overlay.render(rc);
-    } catch (error) {
-      console.error("[fnc] overlay", error);
-    }
-    ctx.restore();
-  }
+  for (const overlay of o.overlays) if (overlay.layer !== "below") runOverlay(overlay);
   o.trading.render(rc, m.bars, o.barIndexAt, (i) => m.timeScale.indexToX(i), o.tradingLabels, badges);
   o.drawings.render(rc, badges, m.bars, o.barIndexAt);
   ctx.restore();
@@ -2802,6 +2811,8 @@ var Chart = class {
   cleanups = [];
   drawings;
   overlays = [];
+  legendExtras = [];
+  legendSeq = 0;
   trading;
   tradingSync;
   tooltipKey = null;
@@ -3778,6 +3789,38 @@ var Chart = class {
   addAlertLine(options) {
     return this.trading.addAlert(options);
   }
+  /**
+   * Adds a row to the legend for something the app draws (see LegendItemOptions). `update()`
+   * changes its name or state; `remove()` takes the row away (the app removes its drawing).
+   */
+  addLegendItem(options) {
+    const item = { ...options, id: `legend-${++this.legendSeq}`, visible: options.visible ?? true };
+    this.legendExtras = [...this.legendExtras, item];
+    this.emitter.emit("legendItemsChange", this.legendExtras);
+    return {
+      update: (patch) => {
+        this.legendExtras = this.legendExtras.map((x) => x.id === item.id ? { ...x, ...patch, visible: patch.visible ?? x.visible } : x);
+        this.emitter.emit("legendItemsChange", this.legendExtras);
+      },
+      remove: () => {
+        if (!this.legendExtras.some((x) => x.id === item.id)) return;
+        this.legendExtras = this.legendExtras.filter((x) => x.id !== item.id);
+        this.emitter.emit("legendItemsChange", this.legendExtras);
+      }
+    };
+  }
+  /** The app's legend rows, in the order they were added. */
+  get legendItems() {
+    return this.legendExtras;
+  }
+  /** The legend's 👁 on an app row: tells the app (onToggle) and remembers the state. */
+  setLegendItemVisible(id, visible) {
+    const item = this.legendExtras.find((x) => x.id === id);
+    if (!item || item.visible === visible) return;
+    this.legendExtras = this.legendExtras.map((x) => x.id === id ? { ...x, visible } : x);
+    item.onToggle?.(visible);
+    this.emitter.emit("legendItemsChange", this.legendExtras);
+  }
   /**
    * Paints `overlay` on the price pane every frame (see ChartOverlay). `redraw()` asks for a
    * new frame after its data changed; `remove()` takes it off.

package/dist/objects/types.d.ts

@@ -29,6 +29,11 @@ export interface ObjectRenderContext {
  */
 export interface ChartOverlay {
     render(rc: ObjectRenderContext): void;
+    /**
+     * 'below': painted right after the grid, under the candles and indicators (an order-book
+     * heatmap, session shading). Default 'above'.
+     */
+    layer?: 'above' | 'below';
 }
 export type ObjectHit = {
     kind: 'drawing';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnest/charts",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "description": "Canvas charting engine for financial charts",
   "keywords": [
     "chart",