react-native-livechart 3.3.0 → 3.5.0

package/src/types.ts

@@ -100,21 +100,61 @@ export interface ReferenceLine {
    */
   excludeFromRange?: boolean;
   /**
-   * When a Form-A `value` falls outside the visible plot, render a pinned edge
-   * badge with a directional chevron instead of culling the off-screen line.
+   * Render the Form-A value as a **pill badge** — an icon and/or text tag pinned
+   * to a plot edge at the line's value, with a dashed connector running to the
+   * opposite edge (instead of a plain gutter label that collides with the Y-axis
+   * ticks). Auto-pins to the nearest edge with a directional chevron once the
+   * value scrolls off-screen. Ideal for working orders, price alerts, and targets.
+   *
+   * `true` = defaults (left-pinned, the line's label/value), or a
+   * {@link ReferenceLineBadgeConfig} for an `icon`, `text` toggle (icon-only), and
+   * `position`. Supersedes the legacy `offAxisBadge`. Default off.
+   */
+  badge?: boolean | ReferenceLineBadgeConfig;
+  /**
+   * Legacy: when a Form-A `value` falls outside the visible plot, render a pinned
+   * edge badge with a directional chevron instead of culling the off-screen line.
+   * Prefer {@link badge} (which also shows the tag in-range and supports an icon).
    * Typically paired with `excludeFromRange`. Default `false`.
    */
   offAxisBadge?: boolean;
-  /** Localized word shown in the off-axis badge (e.g. "Target"). Falls back to `label`. */
+  /** Localized word shown in the legacy off-axis badge (e.g. "Target"). Falls back to `label`. */
   offAxisBadgeLabel?: string;
-  /** Off-axis badge pill background. Default: theme `tooltipBg`. */
+  /** Badge pill background. Default: theme `tooltipBg`. (Fallback for `badge.background`.) */
   badgeBackground?: string;
-  /** Off-axis badge pill border color. Default: the line `color`. */
+  /** Badge pill border color. Default: the line `color`. (Fallback for `badge.borderColor`.) */
   badgeBorderColor?: string;
-  /** Off-axis badge pill corner radius in pixels. Default `5`. */
+  /** Badge pill corner radius in pixels. Default `5`. (Fallback for `badge.radius`.) */
   badgeRadius?: number;
 }
 
+/**
+ * Pill-badge presentation for a Form-A {@link ReferenceLine} — a working order,
+ * price alert, or target tag. The badge sits at the line's value (pinned to
+ * `position`) with a dashed connector to the opposite edge, and pins to the
+ * nearest edge with a chevron once the value scrolls off-screen.
+ */
+export interface ReferenceLineBadgeConfig {
+  /** Which plot edge the badge pins to. Default `"left"`. */
+  position?: "left" | "right";
+  /**
+   * Leading glyph drawn in the badge — rendered with the chart font, so pass an
+   * emoji-capable font (via the chart `font` prop) for emoji. Like `Marker.icon`.
+   */
+  icon?: string;
+  /**
+   * Show the text label (the line's `label`, plus the value when `showValue`).
+   * Default `true`. Set `false` for an **icon-only** badge.
+   */
+  text?: boolean;
+  /** Pill background. Falls back to `badgeBackground`, then theme `tooltipBg`. */
+  background?: string;
+  /** Pill border color. Falls back to `badgeBorderColor`, then the line `color`. */
+  borderColor?: string;
+  /** Pill corner radius in pixels. Falls back to `badgeRadius`, then `5`. */
+  radius?: number;
+}
+
 /**
  * A time-range segment of the chart — e.g. a pre-market / regular / after-hours
  * session — distinguished with a **scrub-focus** interaction (Robinhood-style
@@ -201,6 +241,61 @@ export interface LineConfig {
   colors?: string[];
 }
 
+/**
+ * Color the line above vs. below a live threshold value — green above, red below
+ * by default. The threshold is **always** a `SharedValue` so it can track a live
+ * benchmark (break-even / average cost, VWAP, previous close, a peg) on the UI
+ * thread without re-rendering. Drives a hard-split line stroke and, optionally, a
+ * tinted profit/loss fill band and a dashed marker line at the threshold.
+ *
+ * The split stroke supersedes `LineConfig.color`/`colors` and segment recoloring
+ * for the main line while a threshold is set.
+ */
+export interface ThresholdConfig {
+  /**
+   * The split value, in Y-axis (price) units. A `SharedValue` — update it with
+   * `.set()` and the split tracks live on the UI thread (break-even, VWAP, the
+   * previous close, a peg, …).
+   */
+  value: SharedValue<number>;
+  /** Stroke color where the line is at/above `value`. Default: palette up-green (`candleUp`). */
+  aboveColor?: string;
+  /** Stroke color where the line is below `value`. Default: palette down-red (`candleDown`). */
+  belowColor?: string;
+  /**
+   * Tint the area between the line and `value` (the profit/loss band) toward the
+   * above/below colors. Independent of the baseline `gradient` fill — set
+   * `gradient={false}` for the threshold band alone. Default `false`.
+   */
+  fill?: boolean;
+  /**
+   * Dashed marker line + optional gutter label at the threshold. `true` → a dashed
+   * line in the palette reference color; object → styled; omit/`false` → none.
+   * Default off.
+   */
+  line?: boolean | ThresholdLineConfig;
+}
+
+/** Dashed marker line drawn at a {@link ThresholdConfig} value. */
+export interface ThresholdLineConfig {
+  /** Label text, e.g. `"Break-even"`. */
+  label?: string;
+  /**
+   * Label side. `"left"` sits just inside the plot at the line's left edge —
+   * clear of the y-axis labels and the live badge; `"right"` uses the right
+   * gutter like a legacy reference line (may overlap y-axis labels). Default `"left"`.
+   */
+  labelPosition?: "left" | "right";
+  /** Line + label color. Defaults to palette `refLine` / `refLabel`. */
+  color?: string;
+  /** Dash pattern `[dashLength, gapLength]` in pixels. Default `[4, 4]`. */
+  intervals?: [number, number];
+  /** Line thickness in pixels. Default `1`. */
+  strokeWidth?: number;
+  /** Append the formatted threshold value to the label. Default `false`. */
+  showValue?: boolean;
+}
+
 /** Area fill gradient beneath the chart line. */
 export interface GradientConfig {
   /** Opacity at the top of the gradient (near the line). Default `0.35`. */
@@ -293,6 +388,71 @@ export interface ScrubConfig {
   panGestureDelay?: number;
 }
 
+/**
+ * Scrub-action ("order ticket") mode for the single-series `LiveChart` (line and
+ * candle). Tap to drop a locked crosshair, drag to fine-tune a **price level**,
+ * then press the right-gutter action badge to fire {@link LiveChartProps.onScrubAction}.
+ *
+ * The reported price is the value at the reticle's **Y position** (a free price
+ * level you choose — the inverse of the value→pixel mapping), NOT the line/candle
+ * value at the reticle's X. That matches how a limit price works (a horizontal
+ * level) and the crosshair badge in pro charting tools. Opt-in (default off).
+ */
+export interface ScrubActionConfig {
+  /** Glyph drawn in the action badge (rendered as chart text, like `Marker.icon`). Default `"+"`. */
+  icon?: string;
+  /** Action-badge background color. Defaults to the accent / badge color. */
+  background?: string;
+  /** Action-badge icon + price text color. Defaults to the badge text color. */
+  iconColor?: string;
+  /** Horizontal level-line color. Defaults to `palette.crosshairLine`. */
+  lineColor?: string;
+  /**
+   * Show the price readout inside the action badge. Default `true`. Set `false`
+   * for an **icon-only** pill (mirrors {@link ReferenceLineBadgeConfig.text}).
+   */
+  text?: boolean;
+  /**
+   * Show a date/time pill where the reticle's vertical line meets the x-axis,
+   * formatted by the chart's `formatTime`. Off by default — for order entry the
+   * reticle's X (time) is incidental to a price *level*; enable it when the time
+   * under the reticle is meaningful (annotations, time-relevant actions, or a full
+   * crosshair readout). Reuses `background` / `iconColor`. Default `false`.
+   */
+  timeBadge?: boolean;
+  /**
+   * Round the reported price to this increment (e.g. `0.01` for cents, `0.5` for
+   * a tick size) so the badge reads round numbers. Omit for the raw value.
+   */
+  snap?: number;
+  /**
+   * A tap on empty plot (outside the reticle + action badge) dismisses the lock
+   * instead of moving it. Default `false` (an empty-plot tap re-places the reticle).
+   */
+  dismissOnTapOutside?: boolean;
+}
+
+/**
+ * Payload for {@link LiveChartProps.onScrubAction} — the chosen price **level**
+ * (from the locked reticle's Y), not the line value at that time.
+ *
+ * The library asserts no buy/sell semantics: derive the side from `price` versus
+ * your own current price (`price < last` is the usual buy-below / sell-above
+ * convention, but stop orders invert it).
+ */
+export interface ScrubActionPoint {
+  /** Chosen price level — the value at the reticle Y, optionally `snap`-rounded. */
+  price: number;
+  /** Unix timestamp in seconds at the reticle X. */
+  time: number;
+  /** Canvas X coordinate of the reticle. */
+  x: number;
+  /** Canvas Y coordinate of the reticle. */
+  y: number;
+  /** In candle mode, the OHLC data of the candle under the reticle X (context only). */
+  candle?: CandlePoint;
+}
+
 /**
  * Props passed to a custom {@link SelectionDotConfig.component} — the dot drawn
  * at the scrub intersection while scrubbing. All positional inputs are
@@ -929,6 +1089,12 @@ export interface LiveChartProps extends LiveChartCoreProps {
    * `mutedColors`). Optional dashed `divider` + `label` mark a segment's edge.
    */
   segments?: ChartSegment[];
+  /**
+   * Color the line above vs. below a live threshold value (break-even / average
+   * cost, VWAP, previous close, a peg). Always a `SharedValue` so the split tracks
+   * live on the UI thread. See {@link ThresholdConfig}.
+   */
+  threshold?: ThresholdConfig;
   /** Render the live value as a large text overlay in the top-left. Default `false`. */
   showValue?: boolean;
   /** Tint the `showValue` text by momentum (green up / red down). Default `false`. */
@@ -962,6 +1128,29 @@ export interface LiveChartProps extends LiveChartCoreProps {
   static?: boolean;
   /** Called when the user scrubs the crosshair. `null` when scrub ends. */
   onScrub?: (point: ScrubPoint | null) => void;
+  /**
+   * Scrub-action ("order ticket") mode: tap to drop a locked crosshair, drag to
+   * fine-tune a **price level**, then press the right-gutter action badge to fire
+   * {@link onScrubAction}. `true` = defaults, `false`/omitted = off, or pass
+   * {@link ScrubActionConfig}. Coexists with `scrub`/`onScrub`. Default off.
+   */
+  scrubAction?: boolean | ScrubActionConfig;
+  /**
+   * Called on the JS thread when the user presses the scrub-action badge. The
+   * payload's `price` is the value at the locked reticle's Y (a chosen price
+   * level), not the line value at that time. See {@link ScrubActionPoint}.
+   */
+  onScrubAction?: (point: ScrubActionPoint) => void;
+  /**
+   * Called on the JS thread when the user taps a reference line's **badge** — the
+   * pill tag drawn for a working order / alert / target (a `ReferenceLine` with a
+   * {@link ReferenceLine.badge}). Receives the tapped line and its index in the
+   * `referenceLines` array, e.g. to open a cancel/edit sheet for that order. Only
+   * badge-tagged Form-A (value) lines are pressable — a plain line has no discrete
+   * hit target. Coexists with `scrub`/`scrubAction`/`markers` (a tap on a badge is
+   * routed here, not to reticle placement). Single-series only.
+   */
+  onReferenceLinePress?: (line: ReferenceLine, index: number) => void;
   /**
    * Called on the JS thread when degen chart shake starts (momentum swing with shake enabled).
    * Not called when `degen` is off or `DegenOptions.shake` is `false`.