@pipsend/charts 2.2.1 → 2.3.1

package/dist/typings.d.ts

@@ -378,6 +378,8 @@ export declare class DrawingToolsManager {
 	private _pointerDownHandler;
 	private _pointerUpHandler;
 	private _pointerCancelHandler;
+	private _lostCaptureHandler;
+	private _windowPointerUpHandler;
 	private _pointerId;
 	/** A press that grabbed a tool already selected it; its click must not undo that. */
 	private _gestureHandled;
@@ -529,6 +531,8 @@ export declare class DrawingToolsManager {
 	private _findToolByExternalId;
 	private _handlePointerDown;
 	private _handlePointerUp;
+	/** Ends the drag when capture is lost without a pointerup ever arriving. */
+	private _handleLostPointerCapture;
 	/**
 	 * Pane element of a tool's series. The engine asserts the series has a pane,
 	 * so the lookup is guarded.
@@ -1111,6 +1115,97 @@ export declare class PositionCalculator {
 	 */
 	getPipConfig(): PipConfig;
 }
+/**
+ * A group of trading levels — entry, take profit and stop loss — drawn as one
+ * unit: a line per level, a label carrying size and P&L, and a connector that
+ * ties the three together.
+ *
+ * Input is not handled here. Every trading line on a chart shares a single
+ * TradingLineController, which is what guarantees that one gesture moves one
+ * level, and that a position line and a plain draggable price line on the same
+ * chart do not fight over the pointer.
+ */
+export declare class PositionLine implements ISeriesPrimitive, ControllableLine {
+	private readonly _chart;
+	private readonly _series;
+	private readonly _id;
+	private readonly _paneView;
+	private readonly _paneViews;
+	private readonly _axisViews;
+	private readonly _colorParser;
+	private readonly _labelLayout;
+	private _options;
+	private _theme;
+	private _requestUpdate?;
+	private _attached;
+	private _hoveredLevel;
+	private _hoveredPart;
+	private _dragLevel;
+	private _priceBeforeDrag;
+	constructor(chart: IChartApi, series: ISeriesApi<SeriesType>, options: PositionLineOptions);
+	attached(param: SeriesAttachedParameter): void;
+	detached(): void;
+	paneViews(): readonly IPrimitivePaneView[];
+	priceAxisViews(): readonly ISeriesPrimitiveAxisView[];
+	updateAllViews(): void;
+	hitTest(x: number, y: number): PrimitiveHoveredItem | null;
+	id(): string;
+	paneIndex(): number;
+	setHoveredPart(part: string | null): void;
+	setHovered(hovered: boolean): void;
+	isDraggable(): boolean;
+	isClickable(): boolean;
+	priceAt(paneY: number): number | null;
+	/**
+	 * Where the level being dragged actually sits. The controller measures the
+	 * pointer against it so the level moves by what the pointer moved, instead
+	 * of jumping to sit under it — which matters most when the label has been
+	 * fanned away from its own line.
+	 */
+	dragAnchorY(): number | null;
+	beginDrag(): void;
+	dragTo(price: number): void;
+	commitDrag(): void;
+	cancelDrag(): void;
+	click(): void;
+	/**
+	 * Updates the group. Any subset of options can be passed; the levels given
+	 * are merged into the current ones, and a level set to `undefined` is
+	 * removed.
+	 */
+	applyOptions(options: PositionLineUpdate): void;
+	/**
+	 * Moves one level to a new price, recomputing its text when the level has a
+	 * `formatText`.
+	 *
+	 * Ignored for a level the user is currently dragging — the gesture owns the
+	 * price until it reports back through
+	 * {@link PositionLineOptions.onDragEnd} or
+	 * {@link PositionLineOptions.onDragCancel}.
+	 */
+	setPrice(level: PositionLineLevel, price: number): void;
+	/**
+	 * Replaces one level's label text. Use this for text that changes on its own
+	 * — a ticking P&L on a fixed entry — rather than with the price.
+	 */
+	setText(level: PositionLineLevel, text: string): void;
+	/**
+	 * The current price of each level that is present.
+	 */
+	prices(): Partial<Record<PositionLineLevel, number>>;
+	options(): PositionLineOptions;
+	/**
+	 * Removes the group from the chart and releases its share of the input
+	 * controller.
+	 */
+	remove(): void;
+	requestUpdate(): void;
+	/** Reads back the label the price axis should draw for a level. */
+	private _axisLabel;
+	private _levelOptions;
+	private _applyPrice;
+	private _buildRendererData;
+}
 /**
  * Gestor de marcadores de posiciones de trading
  */
@@ -2272,6 +2367,26 @@ export declare function createOptionsChart(container: string | HTMLElement, opti
 export declare function createParallelChannelTool(context: DrawingContext, options: ParallelChannelToolOptions): ParallelChannelTool;
 export declare function createPitchforkTool(context: DrawingContext, options: PitchforkToolOptions): PitchforkTool;
 export declare function createPolygonTool(context: DrawingContext, options: PolygonToolOptions): PolygonTool;
+/**
+ * Creates a position line group: entry, take profit and stop loss drawn as one
+ * interactive unit.
+ *
+ * @param series - The series the levels are priced against.
+ * @param chart - The chart the series belongs to.
+ * @param options - The levels and their style.
+ *
+ * @example
+ * ```js
+ * const position = createPositionLine(candleSeries, chart, {
+ *     entry: { price: 4306.79, badge: '1', formatText: () => '+ 2.32 USD' },
+ *     takeProfit: { price: 4349.58, badge: '1', text: '+ 42.79 USD' },
+ *     stopLoss: { price: 4266.06, badge: '1', text: '- 40.73 USD' },
+ *     onClose: (level) => console.log('close', level),
+ *     onDragEnd: (level, price) => console.log(level, 'moved to', price),
+ * });
+ * ```
+ */
+export declare function createPositionLine(series: ISeriesApi<SeriesType>, chart: IChartApi, options: PositionLineOptions): PositionLine;
 /**
  * Crea un gestor de marcadores de posiciones de trading
  *
@@ -3247,6 +3362,18 @@ export interface ControllableLine {
 	isDraggable(): boolean;
 	isClickable(): boolean;
 	setHovered(hovered: boolean): void;
+	/**
+	 * Optional. A line whose hit test names sub-parts — a label, a close button —
+	 * is told which one the pointer is over, so `isDraggable`, `isClickable` and
+	 * `click` can answer for that part rather than for the line as a whole.
+	 */
+	setHoveredPart?(part: string | null): void;
+	/**
+	 * Optional. Where the thing being dragged currently sits, in pane
+	 * coordinates. When a line reports it, the drag keeps the distance between
+	 * the pointer and that point instead of snapping the line under the cursor.
+	 */
+	dragAnchorY?(): number | null;
 	priceAt(paneY: number): number | null;
 	beginDrag(): void;
 	dragTo(price: number): void;
@@ -6034,6 +6161,189 @@ export interface PolygonVertex {
 	time: Time;
 	price: number;
 }
+/**
+ * Configuration for one level (entry, take profit or stop loss) of a position.
+ */
+export interface PositionLineLevelOptions {
+	/**
+	 * The price the level sits at.
+	 */
+	price: number;
+	/**
+	 * The text inside the label, for example `+ 42.79 USD`.
+	 */
+	text?: string;
+	/**
+	 * The text of the badge on the left of the label, for example the position
+	 * size. Hidden when empty.
+	 */
+	badge?: string;
+	/**
+	 * Fills the badge with {@link PositionLineLevelOptions.color} instead of
+	 * drawing it outlined.
+	 *
+	 * @defaultValue `true` for the entry, `false` otherwise
+	 */
+	badgeFilled?: boolean;
+	/**
+	 * The colour of the line, the label's border and its text.
+	 */
+	color?: string;
+	/**
+	 * @defaultValue `1`
+	 */
+	lineWidth?: LineWidth;
+	/**
+	 * @defaultValue `LineStyle.Solid` for the entry, `LineStyle.Dashed` otherwise
+	 */
+	lineStyle?: LineStyle;
+	/**
+	 * Lets the user drag the level to a new price.
+	 *
+	 * @defaultValue `true`
+	 */
+	draggable?: boolean;
+	/**
+	 * Shows the close button on the right of the label.
+	 *
+	 * @defaultValue `true`
+	 */
+	closable?: boolean;
+	/**
+	 * Shows the price label on the price axis.
+	 *
+	 * @defaultValue `true`
+	 */
+	axisLabelVisible?: boolean;
+	/**
+	 * Computes {@link PositionLineLevelOptions.text} from the level's current
+	 * price. Called on every price change, which is what keeps a live P&L in
+	 * step with a drag.
+	 */
+	formatText?: (price: number) => string;
+}
+/**
+ * Configuration for a position line group.
+ */
+export interface PositionLineOptions {
+	/**
+	 * The entry level. Always drawn.
+	 */
+	entry: PositionLineLevelOptions;
+	/**
+	 * The take profit level. Omit for a position without one.
+	 */
+	takeProfit?: PositionLineLevelOptions;
+	/**
+	 * The stop loss level. Omit for a position without one.
+	 */
+	stopLoss?: PositionLineLevelOptions;
+	/**
+	 * @defaultValue `true`
+	 */
+	visible?: boolean;
+	/**
+	 * Draws the vertical line joining the levels, with a handle on each of them.
+	 *
+	 * @defaultValue `true`
+	 */
+	connectorVisible?: boolean;
+	/**
+	 * Distance in pixels between the right edge of the pane and the connector.
+	 *
+	 * @defaultValue `56`
+	 */
+	rightOffset?: number;
+	/**
+	 * Overrides for the shared visual style.
+	 */
+	theme?: Partial<PositionLineTheme>;
+	/**
+	 * Fires when the user starts dragging a level.
+	 */
+	onDragStart?: (level: PositionLineLevel, price: number) => void;
+	/**
+	 * Fires continuously while a level is being dragged.
+	 */
+	onDragMove?: (level: PositionLineLevel, price: number) => void;
+	/**
+	 * Fires once the drag is released. A drag that was cancelled does not report.
+	 */
+	onDragEnd?: (level: PositionLineLevel, price: number) => void;
+	/**
+	 * Fires when a drag ends without committing — the pointer left the chart, or
+	 * Escape was pressed. Together with {@link PositionLineOptions.onDragEnd} it
+	 * guarantees every gesture that started is reported as finished, which is
+	 * what callers need to pause work while a level is under the cursor.
+	 */
+	onDragCancel?: (level: PositionLineLevel, price: number) => void;
+	/**
+	 * Fires when the close button of a level is clicked.
+	 */
+	onClose?: (level: PositionLineLevel) => void;
+	/**
+	 * Fires on a click on a level's label or line that did not drag.
+	 */
+	onClick?: (level: PositionLineLevel, price: number) => void;
+}
+/**
+ * Visual style shared by every level of a position line group.
+ */
+export interface PositionLineTheme {
+	/**
+	 * The label's fill. Defaults to the chart's own background, so the label
+	 * stays readable on light and dark themes alike.
+	 */
+	background?: string;
+	/**
+	 * The label's text colour. Defaults to the level's colour.
+	 */
+	textColor?: string;
+	/**
+	 * The text colour used inside a filled badge.
+	 */
+	badgeTextColor: string;
+	/**
+	 * Corner radius of the label, in pixels.
+	 */
+	borderRadius: number;
+	/**
+	 * Border width of the label, in pixels.
+	 */
+	borderWidth: number;
+	/**
+	 * Horizontal padding inside each cell of the label, in pixels.
+	 */
+	paddingX: number;
+	/**
+	 * Vertical padding inside the label, in pixels.
+	 */
+	paddingY: number;
+	/**
+	 * Font size of the label. Defaults to the chart's layout font size.
+	 */
+	fontSize?: number;
+	/**
+	 * Font family of the label. Defaults to the chart's layout font family.
+	 */
+	fontFamily?: string;
+	/**
+	 * Opacity applied to the label's fill, between 0 and 1. The default is
+	 * opaque: the label carries a price and a P&L, and candles showing through
+	 * it make those harder to read.
+	 */
+	backgroundOpacity: number;
+}
+/**
+ * The shape {@link PositionLine.applyOptions} takes: every field optional, and
+ * a level given as a patch rather than as a whole. A level set to `undefined`
+ * is removed; a level that is not mentioned is left alone.
+ */
+export interface PositionLineUpdate extends Partial<Omit<PositionLineOptions, "entry" | "takeProfit" | "stopLoss">> {
+	entry?: Partial<PositionLineLevelOptions>;
+	takeProfit?: Partial<PositionLineLevelOptions>;
+	stopLoss?: Partial<PositionLineLevelOptions>;
+}
 /**
  * Opciones para el gestor de posiciones
  */
@@ -6625,6 +6935,31 @@ export interface SeriesMarkerBase<TimeType> {
 	 * Required when using {@link SeriesMarkerPricePosition} position type.
 	 */
 	price?: number;
+	/**
+	 * The colour of the marker's text.
+	 *
+	 * For the `tag` shape the text sits on top of {@link SeriesMarkerBase.color},
+	 * so this defaults to white. Other shapes draw the text in `color`.
+	 */
+	textColor?: string;
+	/**
+	 * The colour of the marker's outline. Only used by the `tag` shape.
+	 *
+	 * @defaultValue no outline
+	 */
+	borderColor?: string;
+	/**
+	 * The width of the marker's outline in pixels. Only used by the `tag` shape.
+	 *
+	 * @defaultValue `1` when {@link SeriesMarkerBase.borderColor} is set
+	 */
+	borderWidth?: number;
+	/**
+	 * The corner radius of the `tag` shape's bubble in pixels.
+	 *
+	 * @defaultValue `6`
+	 */
+	borderRadius?: number;
 }
 export interface SeriesMarkerPrice<TimeType> extends SeriesMarkerBase<TimeType> {
 	/**
@@ -7707,6 +8042,14 @@ export type OverlayPriceScaleOptions = Omit<PriceScaleOptions, "visible" | "auto
  */
 export type PercentageFormatterFn = (percentageValue: number) => string;
 export type PitchforkPart = "pivot" | "upper" | "lower" | "body";
+/**
+ * The three levels a position line group can show.
+ */
+export type PositionLineLevel = "entry" | "takeProfit" | "stopLoss";
+/**
+ * The parts of a level that respond to the pointer.
+ */
+export type PositionLinePart = "line" | "body" | "close";
 /**
  * Tipo de posición de trading
  */
@@ -7775,8 +8118,12 @@ export type SeriesMarkerPosition = SeriesMarkerBarPosition | SeriesMarkerPricePo
 export type SeriesMarkerPricePosition = "atPriceTop" | "atPriceBottom" | "atPriceMiddle";
 /**
  * Represents the shape of a series marker.
+ *
+ * `tag` draws the text inside a rounded bubble with a pointer aimed at the
+ * anchor, which is what trading platforms use for BUY/SELL callouts. The other
+ * shapes draw the text next to the shape instead.
  */
-export type SeriesMarkerShape = "circle" | "square" | "arrowUp" | "arrowDown";
+export type SeriesMarkerShape = "circle" | "square" | "arrowUp" | "arrowDown" | "tag";
 /**
  * The visual stacking order for the markers within the chart.
  *

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.2.1",
+  "version": "2.3.1",
   "name": "@pipsend/charts",
   "author": "Pipsend",
   "license": "SEE LICENSE IN LICENSE",