react-native-livechart 3.4.0 → 3.5.1

package/src/draw/markerAtlas.ts

@@ -74,7 +74,9 @@ export function markerAppearanceSig(m: Marker): string {
 
 /** One packed glyph in the atlas image: its source rect + box size. */
 export interface AtlasCell {
+  /** Source rect into the (hi-res) atlas texture, in **device** pixels. */
   rect: SkRect;
+  /** Logical (DPR-independent) cell width/height, used to center the blit. */
   w: number;
   h: number;
 }
@@ -84,9 +86,16 @@ export interface MarkerAtlas {
   image: SkImage | null;
   /** appearance-signature → cell. */
   cells: Record<string, AtlasCell>;
+  /**
+   * Device-pixel scale the texture was rasterized at. Cell `rect`s are in
+   * texture (device) pixels, while `w`/`h` stay in logical pixels — so the
+   * per-frame blit must apply an `RSXform` scale of `1 / scale` to map the
+   * hi-res cell back to its logical on-canvas size. See `buildMarkerAtlas`.
+   */
+  scale: number;
 }
 
-const EMPTY_ATLAS: MarkerAtlas = { image: null, cells: {} };
+const EMPTY_ATLAS: MarkerAtlas = { image: null, cells: {}, scale: 1 };
 
 function fillPaint(color: string): SkPaint {
   const p = Skia.Paint();
@@ -258,11 +267,18 @@ function cellSpec(m: Marker, palette: LiveChartPalette, font: SkFont): CellSpec
  *
  * Connector kinds (see `isConnectorMarker`) are skipped — they render via a
  * self-projecting fallback component.
+ *
+ * The texture is rasterized at `scale` (the screen's device-pixel ratio) so the
+ * cells carry enough resolution to stay crisp when blitted onto a retina canvas
+ * — every glyph is recorded in logical coords then magnified by `scale`, and the
+ * per-frame `drawAtlas` shrinks it back with an `RSXform` scale of `1 / scale`.
+ * Without this the logical-sized texture is upscaled ~3× on iOS and looks blurry.
  */
 export function buildMarkerAtlas(
   markers: Marker[],
   palette: LiveChartPalette,
   font: SkFont,
+  scale = 1,
 ): MarkerAtlas {
   const seen = new Set<string>();
   const specs: { sig: string; spec: CellSpec }[] = [];
@@ -282,11 +298,16 @@ export function buildMarkerAtlas(
     totalW += specs[i].spec.w;
     if (specs[i].spec.h > maxH) maxH = specs[i].spec.h;
   }
+  // Logical packed size; the texture itself is `scale`× larger in each axis.
   const W = Math.max(1, Math.ceil(totalW));
   const H = Math.max(1, Math.ceil(maxH));
+  const texW = Math.max(1, Math.ceil(W * scale));
+  const texH = Math.max(1, Math.ceil(H * scale));
 
   const recorder = Skia.PictureRecorder();
-  const canvas = recorder.beginRecording(Skia.XYWHRect(0, 0, W, H));
+  const canvas = recorder.beginRecording(Skia.XYWHRect(0, 0, texW, texH));
+  // Magnify so glyphs drawn in logical coords fill the hi-res texture.
+  canvas.scale(scale, scale);
   const cells: Record<string, AtlasCell> = {};
   let x = 0;
   for (let i = 0; i < specs.length; i++) {
@@ -295,10 +316,15 @@ export function buildMarkerAtlas(
     canvas.translate(x, 0);
     spec.draw(canvas, spec.w / 2, H / 2);
     canvas.restore();
-    cells[sig] = { rect: Skia.XYWHRect(x, 0, spec.w, H), w: spec.w, h: H };
+    // Source rect indexes the device-pixel texture; w/h stay logical.
+    cells[sig] = {
+      rect: Skia.XYWHRect(x * scale, 0, spec.w * scale, texH),
+      w: spec.w,
+      h: H,
+    };
     x += spec.w;
   }
   const picture = recorder.finishRecordingAsPicture();
-  const image = drawAsImageFromPicture(picture, { width: W, height: H });
-  return { image, cells };
+  const image = drawAsImageFromPicture(picture, { width: texW, height: texH });
+  return { image, cells, scale };
 }

package/src/hooks/useChartPaths.ts

@@ -22,9 +22,13 @@ export function useChartPaths(
   engine: SingleEngineState,
   padding: ChartPadding,
   morphT?: SharedValue<number>,
+  /** When set, also build `thresholdFillPath` — the band between the line and this
+   *  pixel-Y, closed at the threshold instead of the chart baseline. */
+  thresholdY?: SharedValue<number>,
 ) {
   const lineBuilder = usePathBuilder();
   const fillBuilder = usePathBuilder();
+  const thresholdFillBuilder = usePathBuilder();
 
   const cacheRef = useRef<{
     emptyPath: SkPath;
@@ -105,5 +109,25 @@ export function useChartPaths(
     return b.detach();
   });
 
-  return { linePath, fillPath } as const;
+  // Threshold-anchored fill: the same spline, closed at `thresholdY` instead of the
+  // baseline, so the band lies between the line and the threshold (the profit/loss
+  // area). Painted with the hard-split vertical gradient, the part above the split
+  // shows the above-color and the part below shows the below-color.
+  const thresholdFillPath = useDerivedValue(() => {
+    const cache = cacheRef.current!;
+    if (!thresholdY) return cache.emptyPath;
+    const yT = thresholdY.get();
+    const pts = flatPts.get();
+    const n = pts.length >> 1;
+    if (n < 2 || !Number.isFinite(yT)) return cache.emptyPath;
+    const b = thresholdFillBuilder.value;
+    b.moveTo(pts[0], pts[1]);
+    drawSpline(b, pts, cache.scratch);
+    b.lineTo(pts[(n - 1) * 2], yT);
+    b.lineTo(pts[0], yT);
+    b.close();
+    return b.detach();
+  });
+
+  return { linePath, fillPath, thresholdFillPath } as const;
 }

package/src/hooks/useThreshold.ts

@@ -0,0 +1,63 @@
+import { vec } from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import {
+  thresholdLineY,
+  thresholdSplitPositions,
+  thresholdVisible,
+} from "../math/threshold";
+
+export interface ThresholdGeometry {
+  /** Threshold pixel-Y within the canvas, or NaN before layout / degenerate range. */
+  lineY: SharedValue<number>;
+  /** Whether the threshold sits within the plot area (drives marker-line opacity). */
+  visible: SharedValue<boolean>;
+  /** Vertical gradient end vector, `vec(0, canvasHeight)` — shared by stroke + fill. */
+  gradientEnd: SharedValue<ReturnType<typeof vec>>;
+  /** `[0, t, t, 1]` stop positions for the hard-split gradient — shared by stroke + fill. */
+  splitPositions: SharedValue<number[]>;
+}
+
+/**
+ * Per-frame screen geometry for the threshold split, shared by the stroke
+ * gradient, the profit/loss fill band, and the dashed marker line. Reads the live
+ * threshold value + engine Y-range on the UI thread; the math lives in
+ * `math/threshold` so it stays unit-testable without Reanimated.
+ */
+export function useThreshold(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  value: SharedValue<number>,
+): ThresholdGeometry {
+  const lineY = useDerivedValue(() =>
+    thresholdLineY(
+      value.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
+  const visible = useDerivedValue(() =>
+    thresholdVisible(
+      lineY.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
+  const splitPositions = useDerivedValue(() =>
+    thresholdSplitPositions(lineY.get(), engine.canvasHeight.get()),
+  );
+
+  const gradientEnd = useDerivedValue(() =>
+    vec(0, Math.max(1, engine.canvasHeight.get())),
+  );
+
+  return { lineY, visible, gradientEnd, splitPositions };
+}

package/src/index.ts

@@ -77,6 +77,8 @@ export type {
   SelectionDotRingConfig,
   SeriesConfig,
   ThemeMode,
+  ThresholdConfig,
+  ThresholdLineConfig,
   TradeEvent,
   ValueLineConfig,
   XAxisConfig,

package/src/math/threshold.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure, worklet-safe geometry for the threshold split ({@link ThresholdConfig}).
+ * No SharedValues and no hooks — these are unit-tested directly; `useThreshold`
+ * wires the live SharedValues into them.
+ */
+
+/**
+ * Pixel Y of a threshold value within the plot. Mirrors the line path's value→Y
+ * mapping in `buildLinePoints` (`top + (max - v) / range * chartH`). Returns NaN
+ * when the canvas hasn't laid out yet or the value range is degenerate, so the
+ * line/fill/marker callers can cull instead of drawing at a bogus position.
+ */
+export function thresholdLineY(
+  value: number,
+  displayMin: number,
+  displayMax: number,
+  canvasHeight: number,
+  paddingTop: number,
+  paddingBottom: number,
+): number {
+  "worklet";
+  const range = displayMax - displayMin;
+  const chartH = canvasHeight - paddingTop - paddingBottom;
+  if (canvasHeight <= 0 || range <= 0 || chartH <= 0) return NaN;
+  return paddingTop + ((displayMax - value) / range) * chartH;
+}
+
+/** True when the threshold's Y sits within the plot area (i.e. on-screen). */
+export function thresholdVisible(
+  lineY: number,
+  canvasHeight: number,
+  paddingTop: number,
+  paddingBottom: number,
+): boolean {
+  "worklet";
+  if (!Number.isFinite(lineY) || canvasHeight <= 0) return false;
+  return lineY >= paddingTop && lineY <= canvasHeight - paddingBottom;
+}
+
+/**
+ * Stop positions for the vertical hard-split gradient, paired with the 4-stop
+ * color array `[above, above, below, below]`: `[0, t, t, 1]`, where `t` is the
+ * threshold's fraction down the full canvas (the gradient vector spans
+ * `0 → canvasHeight`), clamped to `[0, 1]`.
+ *
+ * - `t ≤ 0` (threshold above everything) → `[0, 0, 0, 1]` → solid below-color.
+ * - `t ≥ 1` (threshold below everything) → `[0, 1, 1, 1]` → solid above-color.
+ */
+export function thresholdSplitPositions(
+  lineY: number,
+  canvasHeight: number,
+): number[] {
+  "worklet";
+  if (canvasHeight <= 0 || !Number.isFinite(lineY)) return [0, 1, 1, 1];
+  let t = lineY / canvasHeight;
+  if (t < 0) t = 0;
+  else if (t > 1) t = 1;
+  return [0, t, t, 1];
+}

package/src/types.ts

@@ -241,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`. */
@@ -1034,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`. */