react-native-livechart 4.11.0 → 4.13.0

package/src/types.ts

@@ -63,6 +63,11 @@ export type BadgeVariant = "default" | "minimal";
  * - **Form C** — vertical time band between `from` and `to` (unix seconds).
  */
 export interface ReferenceLine {
+  /**
+   * Stable identifier for this line. Supply a unique value when `referenceLines`
+   * may be reordered so the chart preserves the line's rendered identity.
+   */
+  id?: string;
   /** Form A — the Y-axis value where the horizontal line is drawn. */
   value?: number;
   /** Form B — horizontal band lower Y bound (paired with `valueTo`). */
@@ -254,14 +259,16 @@ export interface ReferenceLineBadgeConfig extends BadgeStyleConfig {
 
 /**
  * Context passed to a custom {@link LiveChartProps.renderReferenceLine} or
- * {@link LiveChartSeriesProps.renderReferenceLine}. The chart floats the element
- * you return over the canvas and pins it to the line's value on
- * the UI thread (vertically centered on the line, horizontally at the badge /
- * label position) — so it tracks the rescaling axis and any drag smoothly without
- * JS re-renders, just like {@link TooltipRenderProps}. Replaces the built-in pill
- * badge / gutter label for that line; return `null`/`undefined` to keep the
- * built-in. Bind the SharedValues to animated text (e.g. an animated `TextInput`)
- * for the value to update on the UI thread too.
+ * {@link LiveChartProps.renderOffAxisReferenceLine} (and their
+ * `LiveChartSeries` counterparts). The chart floats the element you return over
+ * the canvas and pins it to the line's value on the UI thread (vertically centered
+ * on the line, horizontally at the badge / label position) — so it tracks the
+ * rescaling axis and any drag smoothly without JS re-renders, just like
+ * {@link TooltipRenderProps}. `renderReferenceLine` replaces the built-in pill /
+ * gutter label in every state; `renderOffAxisReferenceLine` replaces it only while
+ * the value is pinned above or below the visible plot. Bind the SharedValues to
+ * animated text (e.g. an animated `TextInput`) for the value to update on the UI
+ * thread too.
  */
 export interface ReferenceLineRenderProps {
   /** The reference line being rendered. */
@@ -592,7 +599,9 @@ export interface BadgeConfig extends BadgeStyleConfig {
    * When the chart is scrolled back (see `timeScroll`), move the live-price
    * indicators — the badge, the value line, and the live dot — to the price at
    * the visible window's right edge instead of the live price, so they track the
-   * last visible price as you pan. Default `false`.
+   * last visible price as you pan. The badge's momentum color is derived at that
+   * same historical edge, so incoming live ticks do not recolor it. Default
+   * `false`.
    *
    * @experimental
    */
@@ -638,6 +647,18 @@ export interface YAxisConfig {
    * (the label pool size). Omit (or `0`) for the default dynamic grid.
    */
   count?: number;
+  /**
+   * Place price labels in a shared left-aligned column whose right edge sits
+   * this many pixels from the canvas edge. When omitted, labels keep the
+   * default centered-gutter placement.
+   */
+  labelRightMargin?: number;
+  /**
+   * Gap (px) between the shared price-label column and the end of each grid or
+   * plain reference line. Only applies when {@link labelRightMargin} is set.
+   * Default `0`.
+   */
+  gridEndGap?: number;
   /**
    * Float the price axis over a full-width plot instead of reserving a right
    * gutter for it. The line/candles run all the way to the right edge, and the
@@ -716,10 +737,102 @@ export interface XAxisConfig {
   minGap?: number;
 }
 
+/**
+ * Morfi-style on-canvas tooltip for {@link LiveChartSeries}: a time-range pill
+ * above the guide plus one value pill at every visible series intersection.
+ *
+ * Enable it with `scrub={{ seriesTooltip: true }}` or pass this object to style
+ * and format the readout. It is ignored by the single-series {@link LiveChart}.
+ */
+export interface PerSeriesTooltipConfig {
+  /**
+   * Keep the value pills pinned to the visible series endpoints while idle.
+   * The guide and time pill remain hidden until a scrub starts. Default `false`.
+   */
+  alwaysShow?: boolean;
+  /**
+   * Bucket width used by the time-range pill, in seconds. Omit to infer it from
+   * the latest positive interval in the first visible series.
+   */
+  bucketSeconds?: number;
+  /**
+   * Format a value pill. The second argument identifies the series so one chart
+   * can dispatch to different unit formatters. Defaults to the chart's
+   * `formatValue`.
+   *
+   * Runs on the UI thread and must be worklet-safe.
+   */
+  formatSeriesValue?: (value: number, seriesId: string) => string;
+  /**
+   * Format the time pill from the bucket's start/end unix seconds. The end is
+   * clamped to the chart's current-time anchor, so the live bucket never claims
+   * to end in the future. Defaults to two chart `formatTime` labels joined by
+   * an en dash.
+   *
+   * Runs on the UI thread and must be worklet-safe.
+   */
+  formatTimeRange?: (from: number, to: number) => string;
+  /** Truncate labels longer than this many characters with `…`. Default `14`. */
+  maxLabelChars?: number;
+
+  /** Guide color. Omit to use `scrub.crosshairLineColor`, then the theme. */
+  guideColor?: string;
+  /** Guide stroke width in px. Default `1`. */
+  guideWidth?: number;
+  /**
+   * Guide dash pattern. `true` uses `[3, 3]`; an array supplies explicit Skia
+   * dash intervals; `false` draws a solid guide. Default `[3, 3]`.
+   */
+  guideDashPattern?: boolean | number[];
+
+  /** Time-pill background. Omit to use `scrub.tooltipBackground`, then the theme. */
+  timePillBackground?: string;
+  /** Time-pill text color. Omit to use `scrub.tooltipColor`, then the theme. */
+  timePillColor?: string;
+  /** Time-pill border color. Omit to use `scrub.tooltipBorderColor`, then the theme. */
+  timePillBorderColor?: string;
+  /** Time-pill corner radius in px. Default `6`. */
+  timePillRadius?: number;
+  /** Time-pill horizontal padding in px. Default `8`. */
+  timePillPaddingX?: number;
+  /** Time-pill vertical padding in px. Default `4`. */
+  timePillPaddingY?: number;
+
+  /** Series-pill background. Omit to use `scrub.tooltipBackground`, then the theme. */
+  seriesPillBackground?: string;
+  /** Series label color. Omit to use the theme tooltip text. */
+  seriesPillLabelColor?: string;
+  /** Formatted series value color. Omit to use `seriesPillLabelColor`. */
+  seriesPillValueColor?: string;
+  /** Series-pill border color. Omit to use `scrub.tooltipBorderColor`, then the theme. */
+  seriesPillBorderColor?: string;
+  /** Series-pill corner radius in px. Default `6`. */
+  seriesPillRadius?: number;
+  /** Series-pill horizontal padding in px. Default `8`. */
+  seriesPillPaddingX?: number;
+  /** Series-pill vertical padding in px. Default `4`. */
+  seriesPillPaddingY?: number;
+  /** Diameter of the series-colour dot inside each pill, in px. Default `8`. */
+  seriesPillDotSize?: number;
+  /** Gap between the colour dot and label, in px. Default `6`. */
+  seriesPillDotGap?: number;
+  /** Gap between the label and formatted value, in px. Default `6`. */
+  seriesPillLabelValueGap?: number;
+  /** Diameter of the dot drawn at each line/guide intersection. Default `8`. */
+  intersectionDotSize?: number;
+}
+
 /** Crosshair scrub configuration. */
 export interface ScrubConfig {
   /** Show the value/time tooltip pill while scrubbing. Default `true`. */
   tooltip?: boolean;
+  /**
+   * Opt into the Morfi-style per-series pill tooltip on `LiveChartSeries`.
+   * `true` uses defaults; an object enables and configures it; `false`/omitted
+   * preserves the existing guide-only multi-series scrub. Ignored by
+   * single-series `LiveChart`. Default `false`.
+   */
+  seriesTooltip?: boolean | PerSeriesTooltipConfig;
   /**
    * Opacity of the chart content to the *right* of the crosshair (the "future")
    * while scrubbing — `0` fully fades it out, `1` disables the dim. Implemented
@@ -730,6 +843,33 @@ export interface ScrubConfig {
   dimOpacity?: number;
   /** Vertical crosshair line stroke. Omit to use theme `crosshairLine`. */
   crosshairLineColor?: string;
+  /** Vertical crosshair line width in px. Default `1`. */
+  crosshairStrokeWidth?: number;
+  /**
+   * Extend the vertical crosshair line past the plot's top and bottom edges by
+   * this many px. A measured top custom-tooltip stop remains unchanged so the
+   * line does not draw through the tooltip. Negative values are clamped to `0`.
+   * Default `0`.
+   */
+  crosshairOvershoot?: number;
+  /**
+   * Fade the crosshair as it approaches the live edge. Set `false` to keep the
+   * line, selection dot, and tooltip fully opaque while scrubbing. The trailing
+   * content dim keeps its own edge fade. Default `true`.
+   */
+  crosshairFade?: boolean;
+  /**
+   * Distance in px over which the visible crosshair fades as it approaches the
+   * live edge. Applies to the line, selection dot, and tooltip when
+   * `crosshairFade` is enabled; the trailing-content dim keeps its existing
+   * fade. Negative values are clamped to `0`. Default `4`.
+   */
+  crosshairFadeDistance?: number;
+  /**
+   * Cap style for the vertical crosshair line. Omit to preserve the existing
+   * Skia default.
+   */
+  crosshairLineCap?: "butt" | "round" | "square";
   /**
    * Dash the vertical crosshair line. `true` → a default `[4, 4]` dash; an array
    * sets explicit Skia dash intervals `[on, off, …]` in px. Omit / `false` → a
@@ -797,6 +937,14 @@ export interface ScrubConfig {
    * `false` / omitted keeps the overlays visible while scrubbing (default).
    */
   hideOverlaysOnScrub?: boolean;
+  /**
+   * Keep plain scrubbing inside the horizontal plot bounds. A gesture that
+   * starts in the Y-axis gutter (or beyond either horizontal edge) is ignored;
+   * one that starts inside remains active and clamps to the nearest plot edge
+   * while dragging. Scrub-action gestures retain their existing behavior.
+   * Default `false`.
+   */
+  clampToPlot?: boolean;
 }
 
 /**
@@ -965,7 +1113,8 @@ export interface ChartScale {
 
 /**
  * The price↔pixel / time↔pixel bridge handed to a custom
- * {@link LiveChartProps.renderOverlay}.
+ * {@link LiveChartProps.renderOverlay} or
+ * {@link LiveChartSeriesProps.renderOverlay}.
  *
  * **Easiest path — the `usePriceY` / `useTimeX` hooks.** They project a price / time
  * to a `SharedValue<number>` that tracks the live axis for you; just read it in
@@ -1620,6 +1769,15 @@ export interface TimeScrollConfig {
    * if set, otherwise `500`.
    */
   scrubHoldMs?: number;
+  /**
+   * Hide the live badge, dot, and dashed value line while scrolled back through
+   * history. Default `true`: all three mark the LIVE price, which is off-screen
+   * once the window is frozen behind the live edge, so they'd point at a price
+   * that isn't in view. Set `false` to keep them visible while scrolled back.
+   * Ignored when `badge.followViewEdge` is on — there the group tracks the
+   * visible edge price, which IS in view.
+   */
+  hideLiveOnScrollBack?: boolean;
 }
 
 /**
@@ -2008,8 +2166,9 @@ export interface LiveChartCoreProps {
    *
    * Defaults differ per chart: `LiveChart` shows it (`true`); `LiveChartSeries`
    * hides it (`false`) — with multiple lines the dot can only track the leading
-   * series, so the crosshair + per-series tooltips mark the scrub point instead.
-   * Pass `true` / a config to opt a multi-series chart in.
+   * series. The crosshair — and, when enabled, the per-series tooltip's own
+   * intersection dots — mark the scrub point instead. Pass `true` / a config to
+   * opt a multi-series chart in.
    */
   selectionDot?: boolean | SelectionDotConfig;
   /** Called once when the user starts scrubbing/panning the chart. */
@@ -2161,19 +2320,36 @@ export interface LiveChartProps extends LiveChartCoreProps {
    * pins it to the line's value on the UI thread (see {@link ReferenceLineRenderProps}),
    * so it tracks the rescaling axis and any drag without JS re-renders. Called per
    * Form-A line; return `null`/`undefined` to keep that line's built-in tag. Works
-   * with `badge: false` too (replace the plain gutter label). Single-series only.
+   * with `badge: false` too (replace the plain gutter label). For a left- or
+   * right-pinned `badge`, the chart retains the dashed connector and measures the
+   * custom tag so the connector starts at its outer edge. Single-series only.
    */
   renderReferenceLine?: (
     ctx: ReferenceLineRenderProps,
   ) => ReactElement | null | undefined;
+  /**
+   * Render only a Form-A line's **off-axis** tag as a custom React Native element.
+   * The chart keeps the standard Skia tag / gutter label while the value is in
+   * range, then switches to this element when it pins above or below the plot.
+   * With a left- or right-pinned `badge` (or legacy `offAxisBadge`), its dashed
+   * connector stays native and begins after the measured custom tag. Return
+   * `null`/`undefined` to opt a line out based on its static `line` / `index`;
+   * use the `edge` SharedValue inside the returned element to animate a caret.
+   * `renderReferenceLine` takes precedence if both callbacks handle one line.
+   * Single-series only.
+   */
+  renderOffAxisReferenceLine?: (
+    ctx: ReferenceLineRenderProps,
+  ) => ReactElement | null | undefined;
   /**
    * Collapse Form-A reference lines whose handles sit near the same value into a
    * single count handle (e.g. a stack of working orders at adjacent prices reads
    * as one "×3" tag). `true` = defaults, `false`/omitted = off, or pass a
    * {@link ReferenceLineGroupingConfig} to tune the proximity radius. Lines a
-   * {@link LiveChartProps.renderReferenceLine} owns are excluded (their custom tag
-   * draws itself), so the count reflects only collapsed built-in tags. Single-series
-   * only. Default off.
+   * {@link LiveChartProps.renderReferenceLine} or
+   * {@link LiveChartProps.renderOffAxisReferenceLine} owns are excluded (their
+   * custom tag draws itself), so the count reflects only collapsed built-in tags.
+   * Single-series only. Default off.
    */
   referenceLineGrouping?: boolean | ReferenceLineGroupingConfig;
   /**
@@ -2195,18 +2371,39 @@ export interface LiveChartProps extends LiveChartCoreProps {
 export interface LiveChartSeriesProps extends LiveChartCoreProps {
   /** Array of series definitions. Must be a SharedValue for UI-thread reads. */
   series: SharedValue<SeriesConfig[]>;
+  /**
+   * Render a custom overlay floated over the canvas, handed the live
+   * price↔pixel / time↔pixel {@link ChartOverlayContext}. Use its `scale` snapshot
+   * and mapping worklets to position React Native UI against this chart's resolved
+   * plot bounds (including any axis or explicit inset). The tree mounts full-bleed
+   * with `pointerEvents="box-none"`; return `null`/`undefined` for no overlay.
+   */
+  renderOverlay?: (ctx: ChartOverlayContext) => ReactElement | null | undefined;
   /**
    * Render a Form-A reference line's tag as a custom **React Native** element
    * instead of the built-in Skia pill / gutter label. The chart pins the returned
    * element to the line's live Y position on the UI thread (see
    * {@link ReferenceLineRenderProps}), including off-axis edge pinning. Return
    * `null`/`undefined` to keep that line's built-in tag. The line stroke always
-   * remains visible, and `badge.position` / `labelPosition` controls the custom
-   * tag's left, center, or right anchor.
+   * remains visible; a left- or right-pinned badge also keeps its dashed connector,
+   * starting after the measured custom tag. `badge.position` / `labelPosition`
+   * controls the custom tag's left, center, or right anchor.
    */
   renderReferenceLine?: (
     ctx: ReferenceLineRenderProps,
   ) => ReactElement | null | undefined;
+  /**
+   * Render only a Form-A line's **off-axis** tag as a custom React Native element.
+   * The normal in-range Skia tag / gutter label stays visible, while an edge-pinned
+   * custom tag replaces it above or below the plot. A left- or right-pinned
+   * `badge` (or legacy `offAxisBadge`) retains its native dashed connector, measured
+   * against the custom tag. Return `null`/`undefined` to opt a static `line` /
+   * `index` out; use the `edge` SharedValue inside the returned element to animate
+   * its caret. `renderReferenceLine` takes precedence for the same line.
+   */
+  renderOffAxisReferenceLine?: (
+    ctx: ReferenceLineRenderProps,
+  ) => ReactElement | null | undefined;
   /** Called when a series toggle chip is tapped. */
   onSeriesToggle?: (id: string, visible: boolean) => void;
   /**