@pradeepjadhav/trading-reload-chart 1.3.0 → 1.4.0

package/README.md

@@ -253,6 +253,46 @@ export function ChartPanel() {
 - `TradingReload` fills **100%** of that container.
 - Do **not** import chart CSS manually; styles ship with the component (`src/styles/chart.css`).
 
+### Watermark
+
+Add a text watermark (symbol / timeframe label, chart id, etc.) through `config.watermark`.
+It renders on its own canvas **beneath** candles, shapes, trades, and the crosshair, so it
+never intercepts pointer events.
+
+```tsx
+import {
+  TradingReload,
+  type ChartConfig,
+  type DeepPartial,
+} from "@pradeepjadhav/trading-reload-chart";
+
+const config = {
+  watermark: {
+    text: `${symbol}, ${timeframe}`,
+    position: "top-center",
+    fontSize: 24,
+    fontWeight: 700,
+    color: "#FFFFFF",
+    opacity: 0.35,
+  },
+} satisfies DeepPartial<ChartConfig>;
+
+<TradingReload config={config} /* … */ />;
+```
+
+| Option        | Type                                                                                     | Default                                     | Description                              |
+| ------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------- |
+| `text`        | `string`                                                                                 | `""`                                        | Empty text hides the watermark            |
+| `position`    | `"center" \| "top-center" \| "bottom-center" \| "left-center" \| "right-center"`         | `"center"`                                  | Anchor inside the plot area               |
+| `fontSize`    | `number`                                                                                 | `48`                                        | Font size in CSS pixels                  |
+| `fontWeight`  | `number`                                                                                 | `700`                                       | Numeric font weight                       |
+| `fontFamily`  | `string`                                                                                 | `"Inter, system-ui, -apple-system, sans-serif"` | CSS font stack                         |
+| `color`       | `string`                                                                                 | `COLORS.white`                              | Text color                                |
+| `opacity`     | `number`                                                                                 | `0.25`                                      | Clamped to `0` - `1`                      |
+| `padding`     | `number`                                                                                 | `16`                                        | Inset from the plot edge                  |
+
+> Because `config` is deep-merged, you can pass only the keys you want to change.
+
 ### 3. Vite / Create React App
 
 ```tsx
@@ -286,6 +326,7 @@ Import from the package root:
 | `Candle`, `OpenTrade`, `ClosedTrade`, …      | Domain types         |
 | `Shape`, `ShapeToolType`, shape payloads     | Drawing types        |
 | `ChartConfig`, `CHART_CONFIG`, `DeepPartial` | Configuration        |
+| `WatermarkConfig`, `WatermarkPosition`       | Watermark types      |
 | `ClosedTradeIndicator`, trade handle types   | Trade overlay types  |
 
 Controlled props (parent owns state):
@@ -319,7 +360,7 @@ trading-reload-chart/
 │   ├── index.ts          # Public exports
 │   ├── react/            # TradingReload component
 │   ├── chart/            # ChartController, DOM, utils
-│   ├── canvas/layers/    # Canvas layers (candles, shapes, trades, …)
+│   ├── canvas/layers/    # Canvas layers (candles, volume, watermark, shapes, trades, …)
 │   ├── config/           # CHART_CONFIG and types
 │   ├── models/           # Candle, Trade, ChartViewport, … (*.types.ts)
 │   ├── helpers/          # Shared pure utilities
@@ -336,11 +377,12 @@ Type declarations live in `*.types.ts` files next to implementation code (see AG
 
 ## Features
 
-- Layered canvas rendering (volume, candles, shapes, trades, axes, crosshair)
+- Layered canvas rendering (volume, watermark, candles, shapes, trades, axes, crosshair)
 - Pan, horizontal wheel zoom, Ctrl+wheel vertical zoom
 - Drawing tools (trendline, rectangle, path, fib, long/short position)
 - Open trade SL/TP drag with `onTradeModify` on release
 - Closed trade markers
+- Configurable text watermark layer
 - Deep-merge chart `config` over defaults
 
 ---

package/dist/canvas/layers/ShapesLayer/LineShape.d.ts

@@ -1,4 +1,4 @@
-import { ShapeCoordinateConverter, CommonShapeConfig, ShapeHandleHitbox, ShapePoint, ShapeVertex, TrendlineShape } from './ShapesLayer.types';
+import { CommonShapeConfig, ShapeCoordinateConverter, ShapeHandleHitbox, ShapePoint, ShapeVertex, TrendlineShape } from './ShapesLayer.types';
 export declare class LineShape {
     static defaultConfig: CommonShapeConfig;
     static draw({ ctx, shape, converter, config, selected, hovered, }: {

package/dist/canvas/layers/ShapesLayer/PathShape.d.ts

@@ -1,4 +1,4 @@
-import { PathShapeData, ShapeCoordinateConverter, CommonShapeConfig, ShapeHandleHitbox, ShapePoint, ShapeVertex } from './ShapesLayer.types';
+import { CommonShapeConfig, PathShapeData, ShapeCoordinateConverter, ShapeHandleHitbox, ShapePoint, ShapeVertex } from './ShapesLayer.types';
 export declare class PathShape {
     static defaultConfig: CommonShapeConfig;
     static draw({ ctx, shape, converter, config, selected, hovered, }: {

package/dist/canvas/layers/ShapesLayer/RectangleShape.d.ts

@@ -1,4 +1,4 @@
-import { RectangleShapeData, ShapeCoordinateConverter, ShapeHandleHitbox, ShapePoint, ShapeVertex, RectangleShapeConfig } from './ShapesLayer.types';
+import { RectangleShapeConfig, RectangleShapeData, ShapeCoordinateConverter, ShapeHandleHitbox, ShapePoint, ShapeVertex } from './ShapesLayer.types';
 export declare class RectangleShape {
     static defaultConfig: RectangleShapeConfig;
     static draw({ ctx, shape, converter, config, selected, hovered, }: {

package/dist/canvas/layers/ShapesLayer/ShapesLayer.helpers.d.ts

@@ -1,5 +1,5 @@
 import { Candle } from '../../../models/Candle.types';
-import { FibLevelValue, Shape, ShapeBoundingBox, ShapeCoordinateConverter, CommonShapeConfig, ShapeHandleHitbox, ShapeLineStyle, ShapePoint, ShapeVertex } from './ShapesLayer.types';
+import { CommonShapeConfig, FibLevelValue, Shape, ShapeBoundingBox, ShapeCoordinateConverter, ShapeHandleHitbox, ShapeLineStyle, ShapePoint, ShapeVertex } from './ShapesLayer.types';
 export declare const SHAPE_HIT_TOLERANCE = 8;
 export declare const SHAPE_HANDLE_RADIUS = 5;
 export declare const generateShapeId: () => string;

package/dist/canvas/layers/TradeLayer/TradeLayer.types.d.ts

@@ -1,4 +1,4 @@
-import { MissingTradeProtectionHandleRectConfig, ClosedTradeIndicatorArrowConfig as ClosedTradeIndicatorArrowConfig, TemporaryTradeProtectionHandleRectConfig, TradeHandleLineConfig, TradeHandleRectConfig, TradeHandleStyleConfig } from '../../../config/chartConfig.types';
+import { ClosedTradeIndicatorArrowConfig, MissingTradeProtectionHandleRectConfig, TemporaryTradeProtectionHandleRectConfig, TradeHandleLineConfig, TradeHandleRectConfig, TradeHandleStyleConfig } from '../../../config/chartConfig.types';
 import { ChartViewport } from '../../../models/ChartViewport.types';
 import { ClosedTrade, OpenTrade, TradeDirection } from '../../../models/Trade.types';
 /**

package/dist/canvas/layers/WatermarkLayer/WatermarkLayer.d.ts

@@ -0,0 +1,40 @@
+import { WatermarkConfig } from '../../../config/chartConfig.types';
+import { WatermarkLayerOptions } from './WatermarkLayer.types';
+/**
+ * Text watermark drawn on its own canvas beneath the candlestick and
+ * interaction layers, so it never intercepts pointer events and is always
+ * painted over by candles, shapes, trades, and the crosshair.
+ *
+ * @example
+ * ```ts
+ * const layer = new WatermarkLayer({
+ *   canvas,
+ *   config: { ...CHART_CONFIG.watermark, text: "USDJPY, 15m" },
+ * });
+ * layer.resize(800, 600);
+ * layer.render();
+ * ```
+ */
+export declare class WatermarkLayer {
+    #private;
+    constructor(options: WatermarkLayerOptions);
+    setConfig(config: WatermarkConfig): void;
+    /**
+     * Resizes the canvas and stores the plot size used for placement.
+     *
+     * @example
+     * ```ts
+     * layer.resize(800, 600);
+     * ```
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Clears the canvas and paints the watermark when it has text.
+     *
+     * @example
+     * ```ts
+     * layer.render();
+     * ```
+     */
+    render(): void;
+}

package/dist/canvas/layers/WatermarkLayer/WatermarkLayer.helpers.d.ts

@@ -0,0 +1,27 @@
+import { ResolveWatermarkTextPlacementOptions, WatermarkTextPlacement } from './WatermarkLayer.types';
+/**
+ * Resolves the canvas text anchor for a watermark position.
+ *
+ * `textAlign` and `textBaseline` are returned alongside the coordinates so the
+ * caller can apply them to the context before measuring or drawing the text.
+ *
+ * @example
+ * ```ts
+ * const { x, y, textAlign, textBaseline } = resolveWatermarkTextPlacement({
+ *   position: "bottom-center",
+ *   width: 800,
+ *   height: 600,
+ *   padding: 16,
+ * });
+ * ```
+ */
+export declare const resolveWatermarkTextPlacement: (options: ResolveWatermarkTextPlacementOptions) => WatermarkTextPlacement;
+/**
+ * Clamps an opacity into the `0` - `1` range accepted by the canvas context.
+ *
+ * @example
+ * ```ts
+ * clampWatermarkOpacity(1.4); // 1
+ * ```
+ */
+export declare const clampWatermarkOpacity: (opacity: number) => number;

package/dist/canvas/layers/WatermarkLayer/WatermarkLayer.types.d.ts

@@ -0,0 +1,66 @@
+import { WatermarkConfig } from '../../../config/chartConfig.types';
+/**
+ * Constructor options for {@link WatermarkLayer}.
+ *
+ * @example
+ * ```ts
+ * const layer = new WatermarkLayer({
+ *   canvas,
+ *   config: { ...CHART_CONFIG.watermark, text: "USDJPY, 15m" },
+ * });
+ * ```
+ */
+export type WatermarkLayerOptions = {
+    /** Canvas the watermark is painted on. */
+    canvas: HTMLCanvasElement;
+    /** Resolved watermark configuration. */
+    config: WatermarkConfig;
+};
+/**
+ * Text anchor resolved from a {@link WatermarkPosition} and the plot size.
+ *
+ * All values are in CSS pixels.
+ *
+ * @example
+ * ```ts
+ * const placement: WatermarkTextPlacement = {
+ * 	x: 400,
+ * 	y: 16,
+ * 	textAlign: "center",
+ * 	textBaseline: "top",
+ * };
+ * ```
+ */
+export type WatermarkTextPlacement = {
+    /** Horizontal anchor point. */
+    x: number;
+    /** Vertical anchor point. */
+    y: number;
+    /** Canvas text alignment applied before measuring. */
+    textAlign: CanvasTextAlign;
+    /** Canvas text baseline applied before measuring. */
+    textBaseline: CanvasTextBaseline;
+};
+/**
+ * Inputs used to resolve the watermark text anchor.
+ *
+ * @example
+ * ```ts
+ * const placement = resolveWatermarkTextPlacement({
+ *   position: "top-center",
+ *   width: 800,
+ *   height: 600,
+ *   padding: 16,
+ * });
+ * ```
+ */
+export type ResolveWatermarkTextPlacementOptions = {
+    /** Configured watermark position. */
+    position: WatermarkConfig["position"];
+    /** Plot width in CSS pixels. */
+    width: number;
+    /** Plot height in CSS pixels. */
+    height: number;
+    /** Padding between the watermark and the plot edge. */
+    padding: number;
+};

package/dist/chart/createChartDom.types.d.ts

@@ -3,6 +3,7 @@ export type ChartDomElements = {
     layout: HTMLDivElement;
     stack: HTMLDivElement;
     volumeCanvas: HTMLCanvasElement;
+    watermarkCanvas: HTMLCanvasElement;
     candleCanvas: HTMLCanvasElement;
     shapesCanvas: HTMLCanvasElement;
     tradesCanvas: HTMLCanvasElement;

package/dist/chart/utils/resolveWheelZoomAxis.d.ts

@@ -0,0 +1,7 @@
+import { WheelZoomAxis } from './resolveWheelZoomAxis.types';
+/**
+ * Horizontal for a plain wheel, and horizontal for a trackpad pinch so the
+ * gesture zooms the time axis. Vertical stays reserved for a real Ctrl/Cmd +
+ * mouse wheel so existing mouse and keyboard-driven zoom is untouched.
+ */
+export declare const resolveWheelZoomAxis: (event: WheelEvent) => WheelZoomAxis;

package/dist/chart/utils/resolveWheelZoomAxis.types.d.ts

@@ -0,0 +1 @@
+export type WheelZoomAxis = "x" | "y";

package/dist/config/chartConfig.types.d.ts

@@ -116,6 +116,46 @@ export type VolumeConfig = {
     bottomOffset: number;
     minBarHeight: number;
 };
+/**
+ * Placement of the watermark inside the plot area.
+ *
+ * @example `"top-center"`
+ */
+export type WatermarkPosition = "center" | "top-center" | "bottom-center" | "left-center" | "right-center";
+/**
+ * Text watermark rendered on a dedicated canvas beneath the candlestick and
+ * interaction layers.
+ *
+ * @example
+ * ```ts
+ * const watermark: WatermarkConfig = {
+ * 	text: "USDJPY, 15m",
+ * 	position: "top-center",
+ * 	fontSize: 24,
+ * 	fontWeight: 700,
+ * 	color: "#ffffff",
+ * 	opacity: 0.35,
+ * };
+ * ```
+ */
+export type WatermarkConfig = {
+    /** Watermark text. An empty string hides the watermark. */
+    text: string;
+    /** Watermark placement inside the plot area. */
+    position: WatermarkPosition;
+    /** Font size in CSS pixels, before device pixel ratio scaling. */
+    fontSize: number;
+    /** Numeric CSS font weight. */
+    fontWeight: number;
+    /** CSS font family used to measure and paint the watermark. */
+    fontFamily: string;
+    /** Watermark color, any CSS color value. */
+    color: string;
+    /** Watermark opacity between `0` and `1`. */
+    opacity: number;
+    /** Padding in CSS pixels between the watermark and the plot edge. */
+    padding: number;
+};
 /**
  * Crosshair line style.
  *
@@ -633,6 +673,7 @@ export type ChartConfig = {
     zoom: ZoomConfig;
     candles: CandlesConfig;
     volume: VolumeConfig;
+    watermark: WatermarkConfig;
     crosshair: CrosshairConfig;
     tradeHandles: TradeHandlesConfig;
     closedTradeIndicators: ClosedTradeIndicatorsConfig;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { ChartControllerProps, PreviousDay, TradeModifyPayload, } from './c
 export type { DeepPartial } from './chart/utils/deepPartial.types';
 export type { CanvasPoint } from './chart/utils/getCanvasPoint.types';
 export { CHART_CONFIG } from './config/chartConfig';
-export type { ChartConfig, PreviousDayHighLowConfig } from './config/chartConfig.types';
+export type { ChartConfig, PreviousDayHighLowConfig, WatermarkConfig, WatermarkPosition, } from './config/chartConfig.types';
 export type { Candle } from './models/Candle.types';
 export type { ChartCursorState, ChartViewState } from './models/ChartSync.types';
 export type { ChartViewport } from './models/ChartViewport.types';

package/dist/models/Candle.types.d.ts

@@ -55,9 +55,12 @@ export type Candle = {
     /**
      * Current ask price during this candle.
      *
+     * Only the forming candle carries it; feeds that omit a live tick leave it
+     * undefined, so the ask line falls back to this candle's close.
+     *
      * @example `1.0853`
      */
-    ask: number;
+    ask?: number;
     /**
      * `false` while the realtime candle is still forming.
      *

package/dist/trading-reload-chart.css

@@ -1,2 +1,2 @@
-.trading-reload-chart{box-sizing:border-box;outline:none;width:100%;height:100%;overflow:hidden}.trading-reload-chart *,.trading-reload-chart :before,.trading-reload-chart :after{box-sizing:border-box}.trading-reload-chart__layout{--axis-x-height:30px;width:100%;height:100%;display:flex;position:relative;overflow:hidden}.trading-reload-chart__stack{flex:1;height:100%;position:relative;overflow:hidden}.trading-reload-chart canvas{display:block}.trading-reload-chart__volume,.trading-reload-chart__plot,.trading-reload-chart__shapes,.trading-reload-chart__trades,.trading-reload-chart__overlay{width:100%;height:calc(100% - var(--axis-x-height));position:absolute;top:0;left:0}.trading-reload-chart__volume{z-index:0;pointer-events:none}.trading-reload-chart__plot{z-index:1}.trading-reload-chart__shapes{z-index:2}.trading-reload-chart__trades{z-index:3}.trading-reload-chart__overlay{z-index:4}.trading-reload-chart__axis-x{width:100%;height:var(--axis-x-height);z-index:5;position:absolute;bottom:0;left:0}.trading-reload-chart__axis-y{height:calc(100% - var(--axis-x-height));z-index:4;flex-shrink:0;position:relative}
+.trading-reload-chart{box-sizing:border-box;outline:none;width:100%;height:100%;overflow:hidden}.trading-reload-chart *,.trading-reload-chart :before,.trading-reload-chart :after{box-sizing:border-box}.trading-reload-chart__layout{--axis-x-height:30px;width:100%;height:100%;display:flex;position:relative;overflow:hidden}.trading-reload-chart__stack{flex:1;height:100%;position:relative;overflow:hidden}.trading-reload-chart canvas{display:block}.trading-reload-chart__volume,.trading-reload-chart__watermark,.trading-reload-chart__plot,.trading-reload-chart__shapes,.trading-reload-chart__trades,.trading-reload-chart__overlay{width:100%;height:calc(100% - var(--axis-x-height));position:absolute;top:0;left:0}.trading-reload-chart__volume{z-index:0;pointer-events:none}.trading-reload-chart__watermark{z-index:1;pointer-events:none}.trading-reload-chart__plot{z-index:2}.trading-reload-chart__shapes{z-index:3}.trading-reload-chart__trades{z-index:4}.trading-reload-chart__overlay{z-index:5}.trading-reload-chart__axis-x{width:100%;height:var(--axis-x-height);z-index:6;position:absolute;bottom:0;left:0}.trading-reload-chart__axis-y{height:calc(100% - var(--axis-x-height));z-index:4;flex-shrink:0;position:relative}
 /*$vite$:1*/