react-native-livechart 3.2.0 → 3.4.0

package/src/math/segments.ts

@@ -0,0 +1,173 @@
+import type { ResolvedSegment } from "../core/resolveSegment";
+
+/** Screen-space x-extent of a segment band, recomputed each frame. */
+export interface SegmentBandX {
+  visible: boolean;
+  /** Band left edge (px), clamped into the plot. */
+  bx1: number;
+  /** Band right edge (px), clamped into the plot. */
+  bx2: number;
+}
+
+const INVISIBLE_BAND: SegmentBandX = { visible: false, bx1: 0, bx2: 0 };
+
+/**
+ * Project a segment's `[from, to]` time range (unix seconds) to a clamped x-pixel
+ * band within the plot `[x1, x2]`. Mirrors the time-band logic in
+ * `useReferenceLine`: an omitted `from` extends to the left edge (window start),
+ * an omitted `to` extends to the live edge (`now = winStart + win`). Swaps a
+ * reversed range, culls a fully off-screen one, and clamps a partial one.
+ */
+export function segmentBandX(
+  from: number | undefined,
+  to: number | undefined,
+  winStart: number,
+  win: number,
+  x1: number,
+  x2: number,
+): SegmentBandX {
+  "worklet";
+  if (win <= 0 || x2 <= x1) return INVISIBLE_BAND;
+  const chartW = x2 - x1;
+  const f = from ?? winStart;
+  const t = to ?? winStart + win;
+
+  let bx1 = x1 + ((f - winStart) / win) * chartW;
+  let bx2 = x1 + ((t - winStart) / win) * chartW;
+  if (bx2 < bx1) {
+    const tmp = bx1;
+    bx1 = bx2;
+    bx2 = tmp;
+  }
+  if (bx2 < x1 || bx1 > x2) return INVISIBLE_BAND;
+  if (bx1 < x1) bx1 = x1;
+  if (bx2 > x2) bx2 = x2;
+  return { visible: true, bx1, bx2 };
+}
+
+/** Horizontal stroke gradient for the recolored line segments. */
+export interface SegmentGradient {
+  colors: string[];
+  positions: number[];
+}
+
+/**
+ * Build the horizontal gradient applied to the line stroke itself, implementing
+ * "scrub focus" (the Robinhood model): the whole line is its plain `baseColor`
+ * until the user scrubs (or a segment is forced `active`). While focused, the
+ * segment under the scrub — or the `active` one — stays `baseColor` (full), and
+ * every OTHER `recolorLine` segment is de-emphasized with its own `mutedColor` /
+ * `mutedColors` (a different hue and/or a reduced alpha that fades it). Because it
+ * paints the line directly (not a layer on top), an alpha-reduced color genuinely
+ * lowers the line's opacity there.
+ *
+ * Stop positions are fractions of the full canvas width — the same coordinate
+ * space as the gradient's `start`/`end` vectors. Each de-emphasized segment
+ * contributes `base@f1 → color(s) across [f1,f2] → base@f2`, with duplicate
+ * positions at the boundaries producing hard edges. The Skia gradient requires
+ * non-decreasing positions, so stops are emitted in ascending x order and never
+ * allowed to step backwards — overlapping/reversed/clamped segments can therefore
+ * never feed a non-monotonic array.
+ *
+ * Returns `null` when the line should be uniform: not scrubbing and nothing
+ * `active`, or when every segment is the focused one (nothing to de-emphasize).
+ * The caller then strokes the line with its plain solid color.
+ */
+export function segmentLineGradient(
+  segments: ResolvedSegment[],
+  winStart: number,
+  win: number,
+  canvasWidth: number,
+  plotLeft: number,
+  plotRight: number,
+  baseColor: string,
+  scrubActive: boolean,
+  scrubX: number,
+): SegmentGradient | null {
+  "worklet";
+  if (win <= 0 || canvasWidth <= 0 || plotRight <= plotLeft) return null;
+
+  // Focus mode is on only while scrubbing or when a segment is forced `active`.
+  // Off → the whole line is its plain base color (segments are indistinguishable).
+  let focusMode = scrubActive;
+  if (!focusMode) {
+    for (let i = 0; i < segments.length; i++) {
+      if (segments[i].recolorLine && segments[i].active) {
+        focusMode = true;
+        break;
+      }
+    }
+  }
+  if (!focusMode) return null;
+
+  const chartW = plotRight - plotLeft;
+
+  // Collect the NON-focused segments — they get de-emphasized (their mutedColor);
+  // the focused segment (under the scrub, or `active`) stays the base color.
+  const spans: { f1: number; f2: number; cols: string[] }[] = [];
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (!seg.recolorLine) continue;
+
+    const from = seg.from ?? winStart;
+    const to = seg.to ?? winStart + win;
+    let px1 = plotLeft + ((from - winStart) / win) * chartW;
+    let px2 = plotLeft + ((to - winStart) / win) * chartW;
+    if (px2 < px1) {
+      const tmp = px1;
+      px1 = px2;
+      px2 = tmp;
+    }
+    if (px2 < plotLeft || px1 > plotRight) continue;
+    if (px1 < plotLeft) px1 = plotLeft;
+    if (px2 > plotRight) px2 = plotRight;
+
+    const focused =
+      (scrubActive && scrubX >= px1 && scrubX <= px2) || seg.active;
+    if (focused) continue; // the focused segment keeps the full base color
+
+    const f1 = px1 / canvasWidth;
+    const f2 = px2 / canvasWidth;
+    if (f2 <= f1) continue;
+    const cols =
+      seg.mutedColors && seg.mutedColors.length >= 2
+        ? seg.mutedColors
+        : [seg.mutedColor];
+    spans.push({ f1, f2, cols });
+  }
+  if (spans.length === 0) return null; // nothing to de-emphasize → uniform line
+
+  spans.sort((a, b) => a.f1 - b.f1);
+
+  const colors: string[] = [];
+  const positions: number[] = [];
+  let last = 0;
+  const push = (color: string, pos: number) => {
+    // Stops must be non-decreasing for Skia. `px` is already clamped to the plot
+    // (⊆ [0, canvasWidth]) so `pos` is within [0,1]; only the monotonic guard is
+    // needed — it keeps overlapping/reversed spans from stepping backwards.
+    const p = pos < last ? last : pos;
+    colors.push(color);
+    positions.push(p);
+    last = p;
+  };
+
+  push(baseColor, 0);
+  for (let i = 0; i < spans.length; i++) {
+    const span = spans[i];
+    push(baseColor, span.f1); // hard edge: base line up to the segment start
+    const n = span.cols.length;
+    if (n === 1) {
+      push(span.cols[0], span.f1);
+      push(span.cols[0], span.f2);
+    } else {
+      for (let k = 0; k < n; k++) {
+        push(span.cols[k], span.f1 + (k / (n - 1)) * (span.f2 - span.f1));
+      }
+    }
+    push(baseColor, span.f2); // hard edge: back to the base line after the segment
+  }
+  push(baseColor, 1);
+
+  return { colors, positions };
+}

package/src/types.ts

@@ -100,21 +100,112 @@ 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
+ * extended-hours segmentation). At rest the whole line is one uniform color;
+ * while the user scrubs (or when a segment is `active`) the focused segment keeps
+ * the base color and every other segment is de-emphasized by recoloring the line
+ * stroke itself (no overlay). An optional dashed `divider` + `label` mark a
+ * segment's leading edge.
+ */
+export interface ChartSegment {
+  /** Segment start, unix seconds. Omit to extend to the chart's left edge. */
+  from?: number;
+  /** Segment end, unix seconds. Omit to extend to the live edge (now). */
+  to?: number;
+
+  /**
+   * Participate in scrub-focus line styling. At rest the line is one uniform
+   * color; while scrubbing (or when a segment is `active`), the focused segment
+   * keeps the base line color and every OTHER `recolorLine` segment is
+   * de-emphasized with `mutedColor` / `mutedColors`. Default `true`.
+   */
+  recolorLine?: boolean;
+  /** De-emphasis line color, used when this segment is NOT the focused one. An
+   *  alpha-reduced color (e.g. `"rgba(154,160,166,0.4)"`) fades the line — it
+   *  paints the stroke directly, not a layer on top. Defaults to the chart's muted
+   *  palette color (`palette.gridLabel`). */
+  mutedColor?: string;
+  /**
+   * Two or more CSS colors → horizontal gradient across the segment's sub-range
+   * (left → right) for the de-emphasized state, mirroring `LineConfig.colors`.
+   * Takes precedence over `mutedColor` when set.
+   */
+  mutedColors?: string[];
+
+  /** Force this segment to be the focused one without scrubbing — it stays full
+   *  while the others are de-emphasized (e.g. the session is currently after-hours). */
+  active?: boolean;
+
+  /** Draw a vertical dashed divider at the `from` edge (market-close marker). Default `false`. */
+  divider?: boolean;
+  /** Divider color. Defaults to the chart's reference-line color (`palette.refLine`). */
+  dividerColor?: string;
+
+  /** Optional label captioning the divider at the top of the segment. Shown only
+   *  when `divider` is set; drawn in the chart's reference-label color
+   *  (`palette.refLabel`). */
+  label?: string;
+  /** Label horizontal anchor within the segment. Default `"left"`. */
+  labelPosition?: "left" | "right";
+}
+
 /** Per-instance grid-line styling for the horizontal value-axis grid. */
 export interface GridStyleConfig {
   /** Stroke color. Defaults to palette `gridLine`. */
@@ -242,6 +333,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
@@ -871,6 +1027,13 @@ export interface LiveChartProps extends LiveChartCoreProps {
   dot?: boolean | DotConfig;
   /** Horizontal dashed line at the current live value. `true` = defaults, or pass `ValueLineConfig`. */
   valueLine?: boolean | ValueLineConfig;
+  /**
+   * Time-range segments (sessions, after-hours, overnight, etc.). At rest the
+   * line is one uniform color; scrubbing a {@link ChartSegment} — or marking one
+   * `active` — keeps it full while the others de-emphasize (`mutedColor` /
+   * `mutedColors`). Optional dashed `divider` + `label` mark a segment's edge.
+   */
+  segments?: ChartSegment[];
   /** 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`. */
@@ -904,6 +1067,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`.