@vroomchart/react 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -94,6 +94,10 @@ type VroomTheme = {
     crosshair?: VroomColor;
     /** Crosshair target — the hollow ring/dot at the intersection. */
     crosshairTarget?: VroomColor;
+    /** Line-chart-mode close polyline color. Defaults to a neutral foreground. */
+    lineColor?: VroomColor;
+    /** Line-chart-mode polyline stroke width in px. Defaults to 1.5. */
+    lineWidth?: number;
 };
 /** A time window over the candle data, as Unix epoch milliseconds. */
 type VisibleRange = {
@@ -108,8 +112,15 @@ type VisibleRange = {
  *   'draw' — left-clicks place drawing points; panning/zooming are suppressed.
  */
 type ChartMode = 'pan' | 'draw';
+/**
+ * How the price series is drawn.
+ *   'candles' — default: candlestick bodies + wicks.
+ *   'line'    — a single polyline through each candle's close. Volume, indicators,
+ *               overlays, crosshair, and drawings still render.
+ */
+type ChartType = 'candles' | 'line';
 /** Active drawing tool while in `draw` mode. `null` draws nothing. */
-type DrawTool = null | 'line';
+type DrawTool = null | 'line' | 'box' | 'pencil';
 /** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
 type DrawPoint = {
     /** Anchor time as Unix epoch milliseconds (not snapped to a candle slot). */
@@ -117,23 +128,81 @@ type DrawPoint = {
     /** Anchor price. */
     price: number;
 };
-/**
- * A committed drawing. Pass an array of these via the `drawings` prop to render
- * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
- * each time the user finishes drawing. For now only the `'line'` (two-point
- * trendline) type exists.
- */
-type Drawing = {
+/** Fields shared by every drawing type. */
+type DrawingBase = {
     /** Stable unique id (the chart generates one for drawings it creates). */
     id: string;
-    type: 'line';
-    /** The two endpoints, in data space. */
-    points: [DrawPoint, DrawPoint];
-    /** Line color (hex string or packed ARGB number). Default solid blue. */
+    /** Stroke color (hex string or packed ARGB number). Default solid blue. */
     color?: VroomColor;
     /** Stroke width in px. Default 2. */
     width?: number;
 };
+/** A two-point trendline from `points[0]` to `points[1]`. */
+type LineDrawing = DrawingBase & {
+    type: 'line';
+    /** The two endpoints, in data space. */
+    points: [DrawPoint, DrawPoint];
+};
+/**
+ * An axis-aligned rectangle whose two opposite corners are `points[0]` and
+ * `points[1]` (the other two corners are derived).
+ */
+type BoxDrawing = DrawingBase & {
+    type: 'box';
+    /** Two opposite corners, in data space. */
+    points: [DrawPoint, DrawPoint];
+};
+/**
+ * A freehand pencil stroke: an open path through `points`, in order. Unlike the
+ * other tools a stroke has a variable number of points, and once committed it
+ * can only be translated — never reshaped.
+ */
+type PencilDrawing = DrawingBase & {
+    type: 'pencil';
+    /** The path's points in draw order (at least 2), in data space. */
+    points: DrawPoint[];
+};
+/**
+ * A committed drawing. Pass an array of these via the `drawings` prop to render
+ * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
+ * each time the user finishes drawing.
+ *
+ * This is a discriminated union on `type` — narrow on it before reading
+ * `points[1]`, since a `'pencil'` stroke has a variable-length array while
+ * `'line'` and `'box'` are always exactly two points.
+ */
+type Drawing = LineDrawing | BoxDrawing | PencilDrawing;
+/**
+ * Storage adapter for **managed** drawing persistence. Provide it via the
+ * `drawingStore` prop and the chart owns the drawings array itself — loading and
+ * saving through this adapter instead of you wiring the controlled `drawings`
+ * prop + `onDrawing*` callbacks.
+ *
+ * The adapter is an **opaque string key-value store** — the chart serializes
+ * drawings into a **versioned envelope** (`{ v, drawings }`) and hands you the
+ * string; you just persist bytes. Because the library owns the schema and
+ * migrates old payloads on load, adding drawing tools or persisted fields later
+ * never changes this interface — your adapter is written once.
+ *
+ * `marketId` is the chart's `seriesKey`, so drawings are bucketed per market:
+ * they persist across timeframe changes (same key) but not across markets. Both
+ * methods may be async (localStorage is sync; AsyncStorage / MMKV / a REST
+ * backend are async). The chart debounces `save`. Consumers that only handle a
+ * single market can ignore `marketId`.
+ */
+type DrawingStore = {
+    /**
+     * Return the raw string previously handed to `save` for `marketId`, or
+     * `null`/`undefined`/`''` if nothing is stored. Sync or async.
+     */
+    load: (marketId: string) => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Persist the opaque `data` string for `marketId`. Sync or async; the chart
+     * debounces calls. The string is a versioned envelope owned by the library —
+     * store it verbatim, don't parse or reshape it.
+     */
+    save: (marketId: string, data: string) => void | Promise<void>;
+};
 /** RSI indicator config. Rendered in a pane below the candles when enabled. */
 type RSIConfig = {
     enabled?: boolean;
@@ -267,6 +336,18 @@ type VroomChartCoreProps = {
      * devices of different widths.
      */
     defaultCandleWidth?: number;
+    /**
+     * Price-series render style. `'candles'` (default) draws candlesticks;
+     * `'line'` draws a polyline through each candle's close (style it with
+     * `theme.lineColor` / `theme.lineWidth`). All other layers are unaffected.
+     */
+    chartType?: ChartType;
+    /**
+     * Duration (ms) of the animated candle↔line transition when `chartType`
+     * changes. Default ~300. `0` snaps instantly. Ignored (snaps) when the OS
+     * requests reduced motion, which instead uses a plain cross-fade.
+     */
+    transitionMs?: number;
     theme?: VroomTheme;
     /** RSI indicator (pane below the candles). Omit/disable to hide it. */
     rsi?: RSIConfig;
@@ -308,10 +389,30 @@ type VroomChartCoreProps = {
      * Committed drawings to render, anchored to data so they track the candles on
      * pan/zoom. This is a controlled prop: append the value the chart hands you in
      * `onDrawingComplete` to persist it.
+     *
+     * Ignored when `drawingStore` is set (the chart then owns the array itself).
      */
     drawings?: Drawing[];
+    /**
+     * Opt into **managed** drawing persistence: the chart owns the drawings array
+     * internally and loads/saves it through this adapter, keyed by `seriesKey`.
+     * When set, `drawings` and the `onDrawing*` callbacks are ignored. Web only.
+     * Requires `seriesKey` — without one, drawings work in-session but aren't saved.
+     */
+    drawingStore?: DrawingStore;
     /** Fired with the finished drawing when the user completes one. */
     onDrawingComplete?: (drawing: Drawing) => void;
+    /**
+     * Fired after the user drags a selected line's endpoint handle. The payload is
+     * the same drawing (same `id`) with updated `points`; apply it to your
+     * controlled `drawings` state (replace by id). Web only.
+     */
+    onDrawingChange?: (drawing: Drawing) => void;
+    /**
+     * Fired when the user deletes the selected line (Backspace/Delete). Remove the
+     * drawing with this `id` from your controlled `drawings` state. Web only.
+     */
+    onDrawingDelete?: (id: string) => void;
     /**
      * Fired when the chart wants the mode changed — e.g. it requests `'pan'` after
      * the user clicks away from a just-drawn line. Since `mode` is controlled, the
@@ -372,4 +473,15 @@ declare function classifyTransition(prev: Candle[] | null, next: Candle[], serie
  */
 declare function timeframeWindow(oldWindow: VisibleRange, oldStepMs: number, oldLastMs: number, newStepMs: number, newLastMs: number): VisibleRange;
 
-export { type Candle, type ChartMode, type CrosshairEvent, type DataTransition, type DrawPoint, type DrawTool, type Drawing, type LiquidityBand, type LiquidityConfig, type MACDConfig, type MASource, type MovingAverageOverlay, type RSIConfig, type VWAPConfig, type VisibleRange, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };
+/** Current envelope schema version. Bump when the persisted shape changes. */
+declare const DRAWINGS_VERSION = 1;
+/** Wrap the current drawings in a versioned envelope and stringify. */
+declare function serializeDrawings(drawings: Drawing[]): string;
+/**
+ * Parse a stored string back into drawings, migrating older envelopes and
+ * dropping anything malformed or of an unknown drawing `type`. Never throws —
+ * returns `[]` for null/empty/garbage input.
+ */
+declare function deserializeDrawings(raw: string | null | undefined): Drawing[];
+
+export { type Candle, type ChartMode, type ChartType, type CrosshairEvent, DRAWINGS_VERSION, type DataTransition, type DrawPoint, type DrawTool, type Drawing, type DrawingStore, type LiquidityBand, type LiquidityConfig, type MACDConfig, type MASource, type MovingAverageOverlay, type RSIConfig, type VWAPConfig, type VisibleRange, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, deserializeDrawings, inferStepMs, serializeDrawings, timeframeWindow };