@pipsend/charts 2.2.1 → 2.3.0

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,89 @@ 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 _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;
+	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 +2359,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 +3354,12 @@ 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;
 	priceAt(paneY: number): number | null;
 	beginDrag(): void;
 	dragTo(price: number): void;
@@ -6034,6 +6147,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 +6921,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 +8028,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 +8104,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,6 @@
 {
-  "version": "2.2.1",
+  "private": false,
+  "version": "2.3.0",
   "name": "@pipsend/charts",
   "author": "Pipsend",
   "license": "SEE LICENSE IN LICENSE",
@@ -53,7 +54,88 @@
     "bollinger-bands",
     "financial-analysis"
   ],
+  "engines": {
+    "node": ">=22.3"
+  },
   "dependencies": {
     "fancy-canvas": "2.1.0"
+  },
+  "devDependencies": {
+    "@juggle/resize-observer": "3.4.0",
+    "@rollup/plugin-node-resolve": "16.0.1",
+    "@rollup/plugin-replace": "6.0.2",
+    "@rollup/plugin-terser": "0.4.4",
+    "@size-limit/file": "11.2.0",
+    "@size-limit/webpack": "11.2.0",
+    "@types/chai": "5.2.1",
+    "@types/express": "5.0.1",
+    "@types/glob": "8.1.0",
+    "@types/node": "22",
+    "@types/pixelmatch": "5.2.6",
+    "@types/pngjs": "6.0.5",
+    "@typescript-eslint/eslint-plugin": "7.18.0",
+    "@typescript-eslint/eslint-plugin-tslint": "7.0.2",
+    "@typescript-eslint/parser": "7.18.0",
+    "ajv": "7.2.4",
+    "bytes": "3.1.2",
+    "chai": "5.2.0",
+    "chai-exclude": "3.0.1",
+    "cross-env": "7.0.3",
+    "dts-bundle-generator": "9.5.1",
+    "eslint": "8",
+    "eslint-formatter-unix": "8.40.0",
+    "eslint-plugin-deprecation": "3.0.0",
+    "eslint-plugin-import": "2.31.0",
+    "eslint-plugin-unicorn": "56.0.1",
+    "esno": "4.8.0",
+    "glob": "11.0.1",
+    "markdown-it": "14.1.0",
+    "markdown-it-anchor": "9.2.0",
+    "markdownlint-cli": "0.44.0",
+    "npm-run-all": "4.1.5",
+    "rimraf": "6.0.1",
+    "rollup": "4.40.0",
+    "size-limit": "11.2.0",
+    "ts-node": "10.9.2",
+    "ts-patch": "3.3.0",
+    "ts-transformer-properties-rename": "0.17.0",
+    "ts-transformer-strip-const-enums": "2.0.0",
+    "tslib": "2.8.1",
+    "tslint": "6.1.3",
+    "tslint-eslint-rules": "5.4.0",
+    "tslint-microsoft-contrib": "6.2.0",
+    "tsx": "4.19.3",
+    "typescript": "5.5.4",
+    "yargs": "17.7.2"
+  },
+  "scripts": {
+    "prepare": "node scripts/githooks/install.js || true",
+    "clean": "rimraf lib/ dist/",
+    "bundle-dts": "dts-bundle-generator --config dts-config.json",
+    "tsc": "tspc -p tsconfig.prod.json",
+    "tsc-watch": "npm run tsc -- --watch --preserveWatchOutput",
+    "tsc-verify": "node -e \"const fs=require('fs');const p='website/scripts/generate-versions-dts.js'; if(fs.existsSync(p)){require('child_process').execSync('node '+p,{stdio:'inherit'});} else {console.warn('[tsc-verify] skip: '+p+' not found');}\" && tsc -b tsconfig.composite.json",
+    "lint": "npm-run-all -p lint:**",
+    "lint:eslint": "eslint --format=unix ./",
+    "lint:md": "markdownlint -i \"**/node_modules/**\" -i \"**/website/docs/api/**\" -i \"**/website/versioned_docs/**/api/**\" -i \"**/*.mdx\" \"**/*.md\"",
+    "check-dts-docs": "npm-run-all -p check-dts-docs-duplicates check-dts-docs-eslint",
+    "check-dts-docs-duplicates": "node ./scripts/check-typings-for-duplicates.js ./dist/typings.d.ts",
+    "check-dts-docs-eslint": "eslint --format=unix ./dist/typings.d.ts --no-ignore",
+    "check-markdown-links": "node scripts/check-markdown-links.js",
+    "rollup": "rollup -c rollup.config.js",
+    "rollup-watch": "npm run rollup -- --watch",
+    "build": "npm-run-all tsc rollup bundle-dts",
+    "build:watch": "npm-run-all tsc -p tsc-watch rollup-watch",
+    "build:prod": "cross-env NODE_ENV=production npm run build",
+    "build:release": "cross-env BUILD_TAG=release npm run build:prod",
+    "prepare-release": "npm-run-all clean build:release && npm run prepare-package-json-for-release",
+    "prepare-package-json-for-release": "node ./scripts/clean-package-json.js",
+    "size-limit": "size-limit",
+    "verify": "npm-run-all clean -p build:prod check-markdown-links -p lint check-dts-docs tsc-verify test size-limit -p type-tests",
+    "test": "esno --import ./tests/unittests/setup.units.mjs --test './tests/unittests/**/*.spec.ts'",
+    "type-tests": "tsc -b ./src/tsconfig.composite.json && tsc -p ./tests/type-checks/tsconfig.composite.json --noEmit",
+    "e2e:coverage": "esno ./tests/e2e/coverage/runner.ts ./dist/pipsend-charts.standalone.development.js",
+    "e2e:interactions": "esno ./tests/e2e/interactions/runner.ts ./dist/pipsend-charts.standalone.development.js",
+    "e2e:memleaks": "esno ./tests/e2e/memleaks/runner.ts ./dist/pipsend-charts.standalone.development.js"
   }
 }