hyperprop-charting-library 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,55 @@
+# hyperprop-charting-library
+
+Lightweight TypeScript charting library (Canvas 2D) focused on:
+
+- OHLC candlestick rendering
+- pan and zoom interactions
+- price lines and order lines
+- trading-style widgets and callbacks
+- framework-agnostic integration
+
+## Install
+
+```bash
+npm install hyperprop-charting-library
+```
+
+## Quick Start
+
+```ts
+import { createChart, type OhlcDataPoint } from "hyperprop-charting-library";
+
+const root = document.getElementById("chart");
+if (!root) throw new Error("Missing chart container");
+
+const chart = createChart(root, { width: 900, height: 520 });
+
+const data: OhlcDataPoint[] = [
+  { t: "2026-01-01T00:00:00.000Z", o: 100, h: 104, l: 98, c: 102 },
+  { t: "2026-01-02T00:00:00.000Z", o: 102, h: 106, l: 101, c: 105 }
+];
+
+chart.setData(data);
+```
+
+## Full Documentation
+
+- API reference: `docs/API.md`
+- Event contracts: `docs/EVENTS.md`
+- Integration recipes: `docs/RECIPES.md`
+- AI integration context: `docs/AI_CONTEXT.md`
+
+## Core API Surface
+
+- `createChart(element, options)`
+- `chart.setData(data)`
+- `chart.setPriceLines(lines)` / `chart.addPriceLine(line)` / `chart.removePriceLine(id)`
+- `chart.setOrderLines(lines)` / `chart.addOrderLine(line)` / `chart.updateOrderLine(id, patch)` / `chart.removeOrderLine(id)`
+- `chart.onOrderAction(handler)` / `chart.onChartClick(handler)`
+- `chart.setDoubleClickEnabled(enabled)` / `chart.setDoubleClickAction(action)`
+- `chart.resize(width, height)` / `chart.destroy()`
+
+## Scope
+
+- This package is chart rendering + chart interaction only.
+- Playground/demo UI is not part of the runtime API.

package/docs/AI_CONTEXT.md

@@ -0,0 +1,59 @@
+# AI Integration Context
+
+Use this file as context for coding assistants integrating `hyperprop-charting-library`.
+
+## What this library is
+
+- Canvas-based chart rendering and interaction engine.
+- Framework-agnostic (no React/Vue dependency).
+- Strong support for price lines, order lines, and trading-style widgets.
+
+## What this library is not
+
+- Not an order execution engine.
+- Not a broker/exchange API.
+- No persistence/state backend.
+
+All business rules (order lifecycle, fills, validation, permissions) must be handled in app code.
+
+## Integration model
+
+1. App owns source-of-truth state.
+2. App translates state -> `setData`, `setPriceLines`, `setOrderLines`.
+3. App listens to `onOrderAction`/`onChartClick`.
+4. App mutates state.
+5. App re-renders lines/data into chart.
+
+This pattern is required for reliable drag/update behavior during live ticks.
+
+## Canonical event handling
+
+- `move` -> update stored price immediately.
+- custom action (for example `execute`) -> run domain logic in app.
+- `dragging: true` -> interim updates during drag.
+- `dragging: false` -> drag completed.
+
+## Common mistakes to avoid
+
+- Treating chart line visuals as source-of-truth.
+- Putting broker logic inside chart callbacks directly.
+- Ignoring interim drag events while streaming data.
+- Assuming `action` is closed enum. It is open (`string`) by design.
+
+## Useful option groups
+
+- Display: `backgroundColor`, `axis`, `grid`, `watermark`, `crosshair`, `tickerLine`
+- Candles: `candleBodyWidthRatio`, `candleMinWidth`, `candleWickWidth`
+- Stability: `autoScaleSmoothing`, `autoScaleIgnoreLatestCandle`
+- Interaction: `doubleClickEnabled`, `doubleClickAction`
+- Overlays: `priceLines`, `orderLines`
+
+## Suggested docs for AI prompts
+
+When using this library in another repo, include:
+
+1. `docs/API.md`
+2. `docs/EVENTS.md`
+3. this file (`AI_CONTEXT.md`)
+
+That gives enough context for most integration tasks without reading source.

package/docs/API.md

@@ -0,0 +1,198 @@
+# API Reference
+
+## Main Entry
+
+- `createChart(element: HTMLElement, options?: ChartOptions): ChartInstance`
+
+Creates and mounts a chart canvas into `element`.
+
+---
+
+## Types
+
+### `OhlcDataPoint`
+
+```ts
+type OhlcDataPoint = {
+  t: string; // ISO time
+  o: number;
+  h: number;
+  l: number;
+  c: number;
+  v?: number;
+};
+```
+
+### `ChartOptions`
+
+Top-level options:
+
+- `width` (default `720`)
+- `height` (default `360`)
+- `backgroundColor` (default `#ffffff`)
+- `axisColor` (legacy shorthand for axis line/text color)
+- `axis?: AxisOptions`
+- `upColor` (default `#16a34a`)
+- `downColor` (default `#dc2626`)
+- `gridColor` (default `#e2e8f0`)
+- `fontFamily`
+- `candleBodyWidthRatio` (default `0.7`)
+- `candleMinWidth` (default `0.5`)
+- `candleWickWidth` (default `1`)
+- `autoScaleSmoothing` (default `0.16`)
+- `autoScaleIgnoreLatestCandle` (default `true`)
+- `doubleClickEnabled` (default `true`)
+- `doubleClickAction` (`"reset"` | `"placeLimitOrder"`, default `"reset"`)
+- `crosshair?: CrosshairOptions`
+- `grid?: GridOptions`
+- `watermark?: WatermarkOptions`
+- `priceLines?: PriceLineOptions[]`
+- `orderLines?: OrderLineOptions[]`
+- `tickerLine?: TickerLineOptions`
+
+### `AxisOptions`
+
+- `lineColor` (default `#94a3b8`)
+- `textColor` (default `#94a3b8`)
+- `fontSize` (default `12`)
+- `lineWidth` (default `1`)
+
+### `GridOptions`
+
+- `color` (default `#e2e8f0`)
+- `opacity` (default `0.9`)
+- `horizontalLines` (default `true`)
+- `verticalLines` (default `true`)
+- `horizontalTickCount` (default `5`)
+
+### `CrosshairOptions`
+
+- `visible` (default `true`)
+- `color` (default `#94a3b8`)
+- `width` (default `1`)
+- `style` (`"solid" | "dotted" | "dashed"`, default `"dotted"`)
+- `showHorizontal` (default `true`)
+- `showVertical` (default `true`)
+
+### `WatermarkOptions`
+
+- `visible` (default `false`)
+- `text` (default `""`)
+- `color` (default `#94a3b8`)
+- `opacity` (default `0.2`)
+- `fontSize` (default `92`)
+- `fontWeight` (default `700`)
+- `thickness` (stroke width, default `0`)
+
+### `TickerLineOptions`
+
+- `visible` (default `true`)
+- `style` (`"solid" | "dotted" | "dashed"`, default `"dashed"`)
+- `thickness` (default `1`)
+- `color` (default `#22c55e`)
+- `labelBackgroundColor` (default `#22c55e`)
+- `labelTextColor` (default `#0b1220`)
+- `labelBorderRadius` (default `6`)
+
+### `PriceLineOptions`
+
+- `id?: string`
+- `price: number` (required)
+- `label?: string`
+- `visible` (default `true`)
+- `style` (`"solid" | "dotted" | "dashed"`, default `"solid"`)
+- `thickness` (default `1`)
+- `color` (default `#f59e0b`)
+- `labelBackgroundColor` (default `#f59e0b`)
+- `labelTextColor` (default `#0f172a`)
+- `labelBorderRadius` (default `3`)
+- `showLabel` (default `true`)
+
+### `OrderActionButton`
+
+- `text: string` (required)
+- `action: string` (required)
+- `draggable?: boolean`
+- `textColor?: string`
+- `backgroundColor?: string`
+- `borderColor?: string`
+- `borderStyle?: "solid" | "dotted" | "dashed"`
+- `borderRadius?: number`
+- `minWidth?: number`
+- `paddingX?: number`
+- `fullHeight?: boolean`
+- `fontWeight?: number | string`
+
+### `OrderLineOptions`
+
+Required fields:
+
+- `type: "market" | "limit" | "stop" | "takeProfit"`
+- `side: "buy" | "sell"`
+- `price: number`
+
+Common optional fields:
+
+- `id?: string`
+- `behavior?: "static" | "follow"` (default `"static"`)
+- `followPrice?: number`
+- `qty?: number`
+- `pnl?: number`
+- `label?: string`
+- `visible?: boolean` (default `true`)
+- `style?: "solid" | "dotted" | "dashed"` (default `"solid"`)
+- `thickness?: number` (default `1`)
+- `color?: string` (default `#f59e0b`)
+- `labelBackgroundColor?: string`
+- `labelTextColor?: string`
+- `labelBorderRadius?: number` (default `3`)
+- `showCloseButton?: boolean` (default `true`)
+- `widgetPosition?: "left" | "center" | "right"` (default `"left"`)
+- `draggable?: boolean` (default `false`)
+
+Legacy single action button:
+
+- `actionButtonText?: string`
+- `actionButtonAction?: string` (default `"execute"`)
+- `actionButtonTextColor?: string`
+- `actionButtonBackgroundColor?: string`
+- `actionButtonBorderRadius?: number`
+- `actionButtonMinWidth?: number`
+- `actionButtonPaddingX?: number`
+- `actionButtonFullHeight?: boolean`
+- `actionButtonFontWeight?: number | string`
+- `actionButtonBorderColor?: string`
+- `actionButtonBorderStyle?: "solid" | "dotted" | "dashed"`
+
+Multi-button actions:
+
+- `actionButtons?: OrderActionButton[]` (default `[]`)
+
+Connector/fill visuals:
+
+- `connectorToPrice?: number`
+- `connectorColor?: string`
+- `connectorStyle?: "solid" | "dotted" | "dashed"` (default `"dotted"`)
+- `connectorThickness?: number` (default `1`)
+- `connectorAnchorPaddingRight?: number` (default `10`)
+- `fillToPrice?: number`
+- `fillColor?: string`
+
+---
+
+## `ChartInstance` Methods
+
+- `setData(data: OhlcDataPoint[]): void`
+- `setPriceLines(lines: PriceLineOptions[]): void`
+- `addPriceLine(line: PriceLineOptions): string`
+- `removePriceLine(id: string): void`
+- `setOrderLines(lines: OrderLineOptions[]): void`
+- `addOrderLine(line: OrderLineOptions): string`
+- `updateOrderLine(id: string, patch: Partial<OrderLineOptions>): void`
+- `removeOrderLine(id: string): void`
+- `onOrderAction(handler: ((event: OrderActionEvent) => void) | null): void`
+- `onChartClick(handler: ((event: ChartClickEvent) => void) | null): void`
+- `setDoubleClickEnabled(enabled: boolean): void`
+- `setDoubleClickAction(action: "reset" | "placeLimitOrder"): void`
+- `resize(width?: number, height?: number): void`
+- `destroy(): void`

package/docs/EVENTS.md

@@ -0,0 +1,89 @@
+# Events
+
+## `onOrderAction`
+
+Register:
+
+```ts
+chart.onOrderAction((event) => {
+  // handle
+});
+```
+
+Payload type:
+
+```ts
+type OrderActionEvent = {
+  orderId?: string;
+  action: "close" | "cancel" | "move" | "createLimit" | "execute" | string;
+  price?: number;
+  dragging?: boolean;
+  line?: OrderLineOptions;
+};
+```
+
+### Common actions
+
+- `execute`: action button pressed (for example Buy/Sell)
+- `close`: close button pressed (usually market-type line)
+- `cancel`: cancel button pressed (usually pending line)
+- `move`: draggable line moved
+- `createLimit`: double-click action in `placeLimitOrder` mode
+
+### Drag semantics
+
+For draggable actions and lines:
+
+- during drag updates: `dragging: true`
+- on drag end: `dragging: false` (final value)
+
+For `move`:
+
+- `price` contains the new line price.
+
+### Notes
+
+- `action` is intentionally open (`string`) so app code can define custom actions.
+- `line` is the line snapshot associated with the hit region when available.
+
+---
+
+## `onChartClick`
+
+Register:
+
+```ts
+chart.onChartClick((event) => {
+  // handle
+});
+```
+
+Payload type:
+
+```ts
+type ChartClickEvent = {
+  x: number;
+  y: number;
+  price?: number;
+  region: "plot" | "x-axis" | "y-axis";
+};
+```
+
+### Behavior
+
+- `region` tells where the click happened.
+- `price` is provided for `plot` region clicks.
+
+---
+
+## Double-click integration
+
+Set behavior:
+
+```ts
+chart.setDoubleClickEnabled(true);
+chart.setDoubleClickAction("placeLimitOrder"); // or "reset"
+```
+
+- `"placeLimitOrder"` emits `onOrderAction({ action: "createLimit", price })` when double-clicking plot.
+- `"reset"` resets viewport/scale behavior.

package/docs/RECIPES.md

@@ -0,0 +1,118 @@
+# Recipes
+
+## Basic chart setup
+
+```ts
+import { createChart } from "hyperprop-charting-library";
+
+const chart = createChart(rootEl, {
+  width: 900,
+  height: 520,
+  backgroundColor: "#101114",
+  upColor: "#2fb171",
+  downColor: "#d35a5a",
+  grid: { opacity: 0.35, horizontalTickCount: 4 }
+});
+```
+
+## Streaming updates
+
+```ts
+chart.setData(nextData);
+```
+
+Use:
+
+- `autoScaleSmoothing` for smoother scale transitions
+- `autoScaleIgnoreLatestCandle` to reduce live-candle jitter
+
+## Add a static alert/level line
+
+```ts
+chart.addPriceLine({
+  price: 6650,
+  label: "Alert",
+  style: "dotted",
+  color: "#f59e0b",
+  showLabel: true
+});
+```
+
+## Add a draggable pending limit line
+
+```ts
+chart.addOrderLine({
+  type: "limit",
+  side: "buy",
+  price: 6480,
+  qty: 1,
+  draggable: true,
+  style: "dotted"
+});
+```
+
+Handle persistence:
+
+```ts
+chart.onOrderAction((event) => {
+  if (event.action === "move" && event.price !== undefined) {
+    // persist new price in your app state
+  }
+});
+```
+
+## Use custom action buttons
+
+```ts
+chart.setOrderLines([
+  {
+    type: "limit",
+    side: "buy",
+    price: 6488,
+    qty: 1,
+    actionButtons: [
+      { text: "Buy", action: "execute", backgroundColor: "#3b82f6" },
+      { text: "TP", action: "previewTp", draggable: true, borderStyle: "dotted" },
+      { text: "SL", action: "previewSl", draggable: true, borderStyle: "dotted" }
+    ]
+  }
+]);
+```
+
+## Draw connector between two prices
+
+```ts
+chart.addOrderLine({
+  type: "takeProfit",
+  side: "sell",
+  price: 6650,
+  connectorToPrice: 6488,
+  connectorStyle: "dashed",
+  connectorAnchorPaddingRight: 34
+});
+```
+
+## Preview fill zone while dragging
+
+```ts
+chart.addOrderLine({
+  type: "takeProfit",
+  side: "sell",
+  price: 6650,
+  fillToPrice: 6488,
+  fillColor: "rgba(45,212,191,0.16)"
+});
+```
+
+## One-click + double-click limit placement
+
+```ts
+chart.setDoubleClickEnabled(true);
+chart.setDoubleClickAction("placeLimitOrder");
+
+chart.onChartClick((event) => {
+  if (event.region === "plot" && event.price !== undefined) {
+    // create one-click preview state in your app
+  }
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperprop-charting-library",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lightweight TypeScript charting core",
   "type": "module",
   "main": "./dist/hyperprop-charting-library.cjs",
@@ -14,7 +14,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "docs"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean && cp \"./dist/index.js\" \"./dist/hyperprop-charting-library.js\" && cp \"./dist/index.cjs\" \"./dist/hyperprop-charting-library.cjs\" && cp \"./dist/index.d.ts\" \"./dist/hyperprop-charting-library.d.ts\"",