react-native-livechart 4.11.0 → 4.12.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
    */
@@ -716,10 +725,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
@@ -965,7 +1066,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 +1722,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 +2119,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 +2273,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 +2324,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;
   /**