react-native-livechart 3.4.0 → 3.5.1

package/src/components/LiveChart.tsx

@@ -31,11 +31,13 @@ import {
   resolveScrub,
   resolveScrubAction,
   resolveSelectionDot,
+  resolveThreshold,
   resolveTradeStream,
   resolveValueLine,
   resolveXAxis,
   resolveYAxis,
 } from "../core/resolveConfig";
+import type { ResolvedThresholdConfig } from "../core/resolveConfig";
 import { resolveSegment } from "../core/resolveSegment";
 import { useLiveChartEngine } from "../core/useLiveChartEngine";
 import { pulseRadialOutset } from "../draw/line";
@@ -57,6 +59,7 @@ import { useModeBlend } from "../hooks/useModeBlend";
 import { useMomentum } from "../hooks/useMomentum";
 import { useSegmentLineGradient } from "../hooks/useSegmentLineGradient";
 import { useSingleChartReverseMorphInputs } from "../hooks/useReverseMorphEngineInputs";
+import { useThreshold } from "../hooks/useThreshold";
 import { useTradeStream } from "../hooks/useTradeStream";
 import { useXAxis } from "../hooks/useXAxis";
 import { useYAxis } from "../hooks/useYAxis";
@@ -69,9 +72,19 @@ import { collectReferenceValues } from "../math/referenceLines";
 import {
   applyPaletteOverride,
   leftEdgeFadeColorsFromBgRgb,
+  parseColorRgb,
   resolveTheme,
 } from "../theme";
-import type { LiveChartProps, Marker, TradeEvent } from "../types";
+import type {
+  LiveChartPalette,
+  LiveChartProps,
+  Marker,
+  TradeEvent,
+} from "../types";
+import {
+  ThresholdBadgeOverlay,
+  ThresholdLineOverlay,
+} from "./ThresholdLineOverlay";
 import { AxisLabelOverlay } from "./AxisLabelOverlay";
 import { BadgeOverlay } from "./BadgeOverlay";
 import { CrosshairOverlay } from "./CrosshairOverlay";
@@ -90,6 +103,32 @@ import { ValueLineOverlay } from "./ValueLineOverlay";
 import { XAxisOverlay } from "./XAxisOverlay";
 import { YAxisOverlay } from "./YAxisOverlay";
 
+/** Translucent fill alpha for the threshold profit/loss band. */
+const THRESHOLD_FILL_OPACITY = 0.16;
+
+/**
+ * Color stops for the threshold's hard-split vertical gradient. Both arrays pair
+ * with the `[0, t, t, 1]` split positions: index 0–1 paint above the split,
+ * 2–3 below. `stroke` is full-strength; `fill` is the same hues at
+ * {@link THRESHOLD_FILL_OPACITY} for the band. Defaults to the palette's semantic
+ * up-green / down-red when colors are omitted.
+ */
+function thresholdStops(
+  cfg: ResolvedThresholdConfig,
+  palette: LiveChartPalette,
+): { stroke: string[]; fill: string[] } {
+  const above = cfg.aboveColor ?? palette.candleUp;
+  const below = cfg.belowColor ?? palette.candleDown;
+  const [ar, ag, ab] = parseColorRgb(above);
+  const [br, bg, bb] = parseColorRgb(below);
+  const aboveFill = `rgba(${ar}, ${ag}, ${ab}, ${THRESHOLD_FILL_OPACITY})`;
+  const belowFill = `rgba(${br}, ${bg}, ${bb}, ${THRESHOLD_FILL_OPACITY})`;
+  return {
+    stroke: [above, above, below, below],
+    fill: [aboveFill, aboveFill, belowFill, belowFill],
+  };
+}
+
 /**
  * Resolves props → configs → theme/layout → engine → per-frame derived values and
  * overlay hooks, returning a single render model. All the chart's wiring lives
@@ -148,6 +187,7 @@ function useLiveChartController({
   valueMomentumColor = false,
   referenceLines,
   segments,
+  threshold,
   gridStyle,
   palette: paletteOverride,
   metrics,
@@ -173,6 +213,9 @@ function useLiveChartController({
   const tradeStreamSV = tradeStream ?? emptyTradeStream;
   const emptyMarkers = useSharedValue<Marker[]>([]);
   const markersSV = markers ?? emptyMarkers;
+  // Stand-in threshold value so `useThreshold` can be called unconditionally
+  // (hooks can't be); the geometry is ignored when no threshold is configured.
+  const emptyThresholdValue = useSharedValue(0);
   const isCandle = mode === "candle";
 
   // ── Resolve feature configs ────────────────────────────────────────────
@@ -185,6 +228,9 @@ function useLiveChartController({
   // Static charts run no gestures, so scrub-action (tap/drag to lock a price) is off.
   const scrubActionCfg = isStatic ? null : resolveScrubAction(scrubAction);
   const gradientCfg = isCandle ? null : resolveGradient(gradient);
+  // Threshold split is a line-mode feature (candle bodies carry their own up/down
+  // colors), so it's inert in candle mode — same as the area gradient.
+  const thresholdCfg = isCandle ? null : resolveThreshold(threshold);
   const valueLineCfg = resolveValueLine(valueLine);
   // Static charts run zero loops: force the pulse off so its `withRepeat`-driven
   // ring never starts (the DotOverlay reads `pulseCfg`, so null = no pulse).
@@ -335,10 +381,23 @@ function useLiveChartController({
   // ── Per-frame derived values ───────────────────────────────────────────
   const { layoutWidth, layoutHeight, onLayout } = useCanvasLayout(engine);
 
-  const { linePath, fillPath } = useChartPaths(
+  // Threshold split geometry (shared by stroke gradient, fill band, marker line).
+  // Called unconditionally with a stand-in value when no threshold is set.
+  const thresholdGeom = useThreshold(
+    engine,
+    effectivePadding,
+    thresholdCfg?.value ?? emptyThresholdValue,
+  );
+  const thresholdStopColors = thresholdCfg
+    ? thresholdStops(thresholdCfg, palette)
+    : null;
+
+  const { linePath, fillPath, thresholdFillPath } = useChartPaths(
     engine,
     effectivePadding,
     reveal.morphT,
+    // Only build the band path when the fill is actually on.
+    thresholdCfg?.fill ? thresholdGeom.lineY : undefined,
   );
   const { upBodiesPath, downBodiesPath, upWicksPath, downWicksPath } =
     useCandlePaths(
@@ -576,6 +635,10 @@ function useLiveChartController({
     resolvedSegments,
     hasRecolorSegments,
     segmentGradient,
+    thresholdCfg,
+    thresholdGeom,
+    thresholdStrokeColors: thresholdStopColors?.stroke ?? null,
+    thresholdFillColors: thresholdStopColors?.fill ?? null,
     badgeUsesRightGutter,
     // theme / layout / fonts
     palette,
@@ -599,6 +662,7 @@ function useLiveChartController({
     onLayout,
     linePath,
     fillPath,
+    thresholdFillPath,
     upBodiesPath,
     downBodiesPath,
     upWicksPath,
@@ -629,10 +693,13 @@ function useLiveChartController({
 
 type LiveChartModel = ReturnType<typeof useLiveChartController>;
 
-/** Main shaken chart stack: grid, fill, line/candles, axes, badge, dot, degen,
- *  markers, and the loading/empty art. The live value text is a separate layer
- *  (ChartValueOverlay) so it sits above the left-edge fade. */
-function ChartStack({ model }: { model: LiveChartModel }) {
+/**
+ * Background fills drawn BENEATH the left-edge fade: the y-axis grid, the area
+ * gradient, and the threshold profit/loss band. Split out from `ChartStack` so
+ * the fade's `dstOut` only softens the fills — the line and everything above it
+ * (drawn in `ChartStack`, after the fade) stay crisp at the left edge.
+ */
+function ChartFillLayer({ model }: { model: LiveChartModel }) {
   const {
     degenShakeTransform,
     yAxisCfg,
@@ -645,41 +712,16 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     badgeUsesRightGutter,
     badgeCfg,
     gridStyleCfg,
+    metricsCfg,
     gradientCfg,
     fillPath,
     gradientEnd,
     gradientColors,
     gradientPositions,
-    valueLineCfg,
-    dotY,
-    allRefLines,
-    resolvedSegments,
-    hasRecolorSegments,
-    segmentGradient,
-    formatValue,
-    lineGroupOpacity,
-    linePath,
-    strokeWidth,
-    lineProp,
-    candleGroupOpacity,
-    upWicksPath,
-    downWicksPath,
-    upBodiesPath,
-    downBodiesPath,
-    xAxisCfg,
-    xAxisEntries,
-    dotX,
-    liveDotOpacity,
-    pulseCfg,
-    dotCfg,
-    degenCfg,
-    degenPack,
-    degenPackRevision,
-    markersActive,
-    markersSV,
-    emptyText,
-    metricsCfg,
-    layoutWidth,
+    thresholdCfg,
+    thresholdGeom,
+    thresholdFillPath,
+    thresholdFillColors,
   } = model;
 
   return (
@@ -715,6 +757,75 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         </Group>
       )}
 
+      {/* Threshold profit/loss band — the area between the line and the threshold,
+          hard-split at the threshold Y into the above/below colors. Independent of
+          the baseline area fill above (set `gradient={false}` for the band alone). */}
+      {thresholdCfg?.fill && thresholdFillColors && (
+        <Group opacity={reveal.fillOpacity}>
+          <Path path={thresholdFillPath} style="fill">
+            <LinearGradient
+              start={vec(0, 0)}
+              end={thresholdGeom.gradientEnd}
+              colors={thresholdFillColors}
+              positions={thresholdGeom.splitPositions}
+            />
+          </Path>
+        </Group>
+      )}
+    </Group>
+  );
+}
+
+/** Main shaken chart stack drawn ABOVE the left-edge fade so the line stays crisp:
+ *  segment dividers, value/reference lines, the line/candles, axes, dot, degen,
+ *  markers, and the loading/empty art. Background fills are in `ChartFillLayer`
+ *  (below the fade); the live value text is `ChartValueOverlay` (above the fade). */
+function ChartStack({ model }: { model: LiveChartModel }) {
+  const {
+    degenShakeTransform,
+    reveal,
+    engine,
+    effectivePadding,
+    palette,
+    skiaFont,
+    badgeCfg,
+    valueLineCfg,
+    dotY,
+    allRefLines,
+    resolvedSegments,
+    hasRecolorSegments,
+    segmentGradient,
+    thresholdCfg,
+    thresholdGeom,
+    thresholdStrokeColors,
+    formatValue,
+    lineGroupOpacity,
+    linePath,
+    strokeWidth,
+    lineProp,
+    candleGroupOpacity,
+    upWicksPath,
+    downWicksPath,
+    upBodiesPath,
+    downBodiesPath,
+    xAxisCfg,
+    xAxisEntries,
+    dotX,
+    liveDotOpacity,
+    pulseCfg,
+    dotCfg,
+    degenCfg,
+    degenPack,
+    degenPackRevision,
+    markersActive,
+    markersSV,
+    emptyText,
+    metricsCfg,
+    layoutWidth,
+  } = model;
+
+  return (
+    <Group transform={degenShakeTransform}>
       {/* Segment dividers + labels (behind the line). The scrub-focus emphasis is
           painted on the line stroke itself, below — this overlay draws no fill. */}
       {resolvedSegments.map((seg, i) => (
@@ -756,6 +867,21 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         />
       ))}
 
+      {/* Threshold marker line + label (behind the chart line). */}
+      {thresholdCfg?.line && (
+        <ThresholdLineOverlay
+          engine={engine}
+          padding={effectivePadding}
+          lineY={thresholdGeom.lineY}
+          visible={thresholdGeom.visible}
+          value={thresholdCfg.value}
+          cfg={thresholdCfg.line}
+          palette={palette}
+          font={skiaFont}
+          formatValue={formatValue}
+        />
+      )}
+
       {/* Chart line (fades out in candle mode). When segments recolor the line, a
           full-width gradient paints the base color outside segments and each
           segment's color within — so the line itself is recolored/faded (alpha in
@@ -769,7 +895,16 @@ function ChartStack({ model }: { model: LiveChartModel }) {
           strokeJoin="round"
           color={lineProp?.color ?? palette.line}
         >
-          {hasRecolorSegments ? (
+          {thresholdCfg && thresholdStrokeColors ? (
+            // Vertical hard split at the threshold Y — supersedes line.colors and
+            // segment recoloring for the stroke while a threshold is set.
+            <LinearGradient
+              start={vec(0, 0)}
+              end={thresholdGeom.gradientEnd}
+              colors={thresholdStrokeColors}
+              positions={thresholdGeom.splitPositions}
+            />
+          ) : hasRecolorSegments ? (
             <LinearGradient
               start={vec(0, 0)}
               end={segmentGradient.gradientEnd}
@@ -865,7 +1000,24 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         </Group>
       )}
 
-      {/* Loading / empty state — before left-edge fade so the squiggle/empty art fades like the chart */}
+      {/* Threshold label badge — on top of the line/dot/markers so it's never
+          painted over (the dashed marker line itself stays behind the line, above). */}
+      {thresholdCfg?.line && (
+        <ThresholdBadgeOverlay
+          engine={engine}
+          padding={effectivePadding}
+          lineY={thresholdGeom.lineY}
+          visible={thresholdGeom.visible}
+          value={thresholdCfg.value}
+          cfg={thresholdCfg.line}
+          palette={palette}
+          font={skiaFont}
+          formatValue={formatValue}
+        />
+      )}
+
+      {/* Loading / empty state — drawn with the line stack (above the fade) so the
+          squiggle/empty art stays crisp, consistent with the line. */}
       <LoadingOverlay
         engine={engine}
         padding={effectivePadding}
@@ -1111,8 +1263,10 @@ export function LiveChart(props: LiveChartProps) {
         accessibilityRole={accessibilityRole}
       >
         <Canvas style={{ flex: 1 }}>
-          {/* Shaken chart stack — left-edge fade is a sibling below so dstOut runs in canvas space */}
-          <ChartStack model={model} />
+          {/* Background fills first, then the left-edge fade (a canvas-space sibling
+              so dstOut blends correctly), then the line stack on top — so the fade
+              softens only the fills and the line stays crisp at the left edge. */}
+          <ChartFillLayer model={model} />
 
           {leftEdgeFadeCfg && (
             <LeftEdgeFade
@@ -1124,6 +1278,9 @@ export function LiveChart(props: LiveChartProps) {
             />
           )}
 
+          {/* Line stack above the fade so the line stays crisp at the left edge. */}
+          <ChartStack model={model} />
+
           {/* Reference-line badges + labels above the fade so they stay crisp. */}
           <ChartRefBadgeLayer model={model} />
 

package/src/components/MarkerOverlay.tsx

@@ -6,6 +6,7 @@ import {
   type SkFont,
 } from "@shopify/react-native-skia";
 import { useMemo, useRef, useState } from "react";
+import { PixelRatio } from "react-native";
 import {
   useDerivedValue,
   useAnimatedReaction,
@@ -189,13 +190,19 @@ export function MarkerOverlay({
   }, [snapshot]);
   // Cells bake in resolved colors; include the palette fields they depend on.
   const paletteKey = `${palette.bgRgb.join(",")}|${palette.line}|${palette.refLine}|${palette.dotUp}|${palette.refLabel}`;
+  // Rasterize at the screen's device-pixel ratio so sprites stay crisp on
+  // retina canvases instead of being upscaled from a logical-sized texture.
+  const dpr = PixelRatio.get();
   const atlas = useMemo(
-    () => buildMarkerAtlas(snapshot, palette, font),
+    () => buildMarkerAtlas(snapshot, palette, font, dpr),
     // eslint-disable-next-line react-hooks/exhaustive-deps -- appearanceKey/paletteKey capture the inputs that change cell pixels
-    [appearanceKey, paletteKey, font],
+    [appearanceKey, paletteKey, font, dpr],
   );
   const cells: Record<string, AtlasCell> = atlas.cells;
   const atlasImage = atlas.image;
+  // Inverse of the texture's device-pixel scale; shrinks each hi-res cell back
+  // to its logical on-canvas size in the per-frame blit.
+  const invScale = 1 / atlas.scale;
 
   // One pooled, ping-ponged projection buffer reused every frame (no per-frame
   // array allocation for the projection itself).
@@ -240,15 +247,16 @@ export function MarkerOverlay({
         if (isConnectorMarker(m)) continue;
         const cell = cells[markerAppearanceSig(m)];
         if (!cell) continue;
-        // Center the cell on the projected point (RSXform: scale 1, no rotation).
+        // Center the cell on the projected point. The cell's source rect is in
+        // device pixels, so scale by 1/dpr to land it at its logical size.
         transforms.push(
-          Skia.RSXform(1, 0, pt.x - cell.w / 2, pt.y - cell.h / 2),
+          Skia.RSXform(invScale, 0, pt.x - cell.w / 2, pt.y - cell.h / 2),
         );
         sprites.push(cell.rect);
       }
       return { transforms, sprites };
     },
-    [cells, markers, engine, padding, series, lineData],
+    [cells, invScale, markers, engine, padding, series, lineData],
   );
   const transforms = useDerivedValue(() => atlasData.get().transforms, [atlasData]);
   const sprites = useDerivedValue(() => atlasData.get().sprites, [atlasData]);

package/src/components/ThresholdLineOverlay.tsx

@@ -0,0 +1,172 @@
+import {
+  DashPathEffect,
+  Group,
+  Path,
+  RoundedRect,
+  Text as SkiaText,
+  type SkFont,
+} from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ResolvedThresholdLineConfig } from "../core/resolveConfig";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { usePathBuilder } from "../hooks/usePathBuilder";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import type { LiveChartPalette } from "../types";
+
+/** Padding inside the marker badge pill, in px (mirrors `ReferenceLineOverlay`). */
+const BADGE_PAD_X = 6;
+const BADGE_PAD_Y = 3;
+const BADGE_RADIUS = 5;
+/** Inset from the canvas edge — small so the badge sits as flush to the edge as possible. */
+const BADGE_EDGE_INSET = 2;
+
+interface ThresholdMarkerProps {
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  lineY: SharedValue<number>;
+  visible: SharedValue<boolean>;
+  value: SharedValue<number>;
+  cfg: ResolvedThresholdLineConfig;
+  palette: LiveChartPalette;
+  font: SkFont;
+  formatValue: (v: number) => string;
+}
+
+/**
+ * The dashed horizontal marker line at a live threshold value, tracking a
+ * `SharedValue` pixel-Y on the UI thread. Drawn **behind** the chart line so the
+ * data line stays the focus; the label badge ({@link ThresholdBadgeOverlay}) is
+ * a separate layer drawn on top. Hidden when the threshold is off-screen.
+ */
+export function ThresholdLineOverlay({
+  engine,
+  padding,
+  lineY,
+  visible,
+  cfg,
+  palette,
+}: ThresholdMarkerProps) {
+  const lineColor = cfg.color ?? palette.refLine;
+  const { strokeWidth, intervals } = cfg;
+
+  const builder = usePathBuilder();
+
+  const linePath = useDerivedValue(() => {
+    const b = builder.value;
+    if (visible.get()) {
+      const y = lineY.get();
+      b.moveTo(padding.left, y);
+      b.lineTo(engine.canvasWidth.get() - padding.right, y);
+    }
+    return b.detach();
+  });
+
+  const opacity = useDerivedValue(() => (visible.get() ? 1 : 0));
+
+  return (
+    <Group opacity={opacity}>
+      <Path
+        path={linePath}
+        style="stroke"
+        strokeWidth={strokeWidth}
+        color={lineColor}
+      >
+        <DashPathEffect intervals={intervals} />
+      </Path>
+    </Group>
+  );
+}
+
+/**
+ * The threshold's label as an opaque badge pill (rounded background + colored
+ * border, like `ReferenceLineOverlay`'s off-axis badge). Drawn **on top** of the
+ * chart line so the label is never painted over, and anchored hard to the plot's
+ * left edge by default (clear of the y-axis labels + live badge) or the right
+ * gutter. Renders nothing when there is no label and no `showValue`.
+ */
+export function ThresholdBadgeOverlay({
+  engine,
+  padding,
+  lineY,
+  visible,
+  value,
+  cfg,
+  palette,
+  font,
+  formatValue,
+}: ThresholdMarkerProps) {
+  const { label, labelPosition, showValue } = cfg;
+  const badgeBackground = palette.tooltipBg;
+  const badgeBorderColor = cfg.color ?? palette.refLine;
+  const labelColor = cfg.color ?? palette.refLabel;
+
+  // Font metrics are stable → read once (getMetrics allocates + crosses JSI).
+  const { fontAscent, baselineOffset, pillH } = (() => {
+    const fm = font.getMetrics();
+    return {
+      fontAscent: fm.ascent,
+      baselineOffset: (fm.ascent + fm.descent) / 2,
+      pillH: fm.descent - fm.ascent + BADGE_PAD_Y * 2,
+    };
+  })();
+
+  const opacity = useDerivedValue(() => (visible.get() ? 1 : 0));
+
+  const labelText = useDerivedValue(() => {
+    if (showValue) {
+      const v = formatValue(value.get());
+      return label ? `${label} ${v}` : v;
+    }
+    return label ?? "";
+  });
+
+  const pillW = useDerivedValue(
+    () => measureFontTextWidth(font, labelText.get()) + BADGE_PAD_X * 2,
+  );
+  // Left: flush to the canvas edge. Right: flush to the right plot edge.
+  const pillX = useDerivedValue(() =>
+    labelPosition === "right"
+      ? engine.canvasWidth.get() - padding.right - BADGE_EDGE_INSET - pillW.get()
+      : BADGE_EDGE_INSET,
+  );
+  const pillY = useDerivedValue(
+    () => lineY.get() - baselineOffset + fontAscent - BADGE_PAD_Y,
+  );
+  const labelX = useDerivedValue(() => pillX.get() + BADGE_PAD_X);
+  const labelY = useDerivedValue(() => lineY.get() - baselineOffset);
+
+  // No label and no value → nothing to draw (hooks above still run, in order).
+  if (label === undefined && !showValue) return null;
+
+  return (
+    <Group opacity={opacity}>
+      <RoundedRect
+        x={pillX}
+        y={pillY}
+        width={pillW}
+        height={pillH}
+        r={BADGE_RADIUS}
+        color={badgeBackground}
+      />
+      <RoundedRect
+        x={pillX}
+        y={pillY}
+        width={pillW}
+        height={pillH}
+        r={BADGE_RADIUS}
+        color={badgeBorderColor}
+        style="stroke"
+        strokeWidth={1}
+      />
+      <SkiaText
+        x={labelX}
+        y={labelY}
+        text={labelText}
+        font={font}
+        color={labelColor}
+      />
+    </Group>
+  );
+}

package/src/core/resolveConfig.ts

@@ -22,6 +22,8 @@ import type {
   SelectionDotConfig,
   SelectionDotProps,
   SelectionDotRingConfig,
+  ThresholdConfig,
+  ThresholdLineConfig,
   TradeEvent,
   ValueLineConfig,
   XAxisConfig,
@@ -224,6 +226,66 @@ export function resolveValueLine(
   return resolveToggle(prop, VALUE_LINE_DEFAULTS, false);
 }
 
+export interface ResolvedThresholdLineConfig {
+  /** undefined → no label. */
+  label: string | undefined;
+  /** Label side; `"left"` sits inside the plot (clear of the y-axis gutter). */
+  labelPosition: "left" | "right";
+  /** undefined → use palette.refLine (line) / palette.refLabel (label) at render time. */
+  color: string | undefined;
+  intervals: [number, number];
+  strokeWidth: number;
+  showValue: boolean;
+}
+
+export interface ResolvedThresholdConfig {
+  /** The live split value (Y-axis units). Read on the UI thread each frame. */
+  value: SharedValue<number>;
+  /** undefined → use palette.candleUp (up-green) at render time. */
+  aboveColor: string | undefined;
+  /** undefined → use palette.candleDown (down-red) at render time. */
+  belowColor: string | undefined;
+  fill: boolean;
+  line: ResolvedThresholdLineConfig | null;
+}
+
+const THRESHOLD_LINE_DEFAULTS: ResolvedThresholdLineConfig = {
+  label: undefined,
+  labelPosition: "left",
+  color: undefined,
+  intervals: [4, 4],
+  strokeWidth: 1,
+  showValue: false,
+};
+
+/**
+ * Resolves the `threshold.line` sub-prop to a config or null (no marker line).
+ * `true` → dashed defaults, object → merged, falsy/undefined → null.
+ */
+export function resolveThresholdLine(
+  prop: boolean | ThresholdLineConfig | undefined,
+): ResolvedThresholdLineConfig | null {
+  return resolveToggle(prop, THRESHOLD_LINE_DEFAULTS, false);
+}
+
+/**
+ * Resolves the `threshold` prop to a fully-typed config or null (disabled).
+ * Presence-gated (like `referenceLines`/`markers`): the required `value`
+ * SharedValue means there is no boolean form — a config object enables it.
+ */
+export function resolveThreshold(
+  prop: ThresholdConfig | undefined,
+): ResolvedThresholdConfig | null {
+  if (!prop) return null;
+  return {
+    value: prop.value,
+    aboveColor: prop.aboveColor,
+    belowColor: prop.belowColor,
+    fill: prop.fill ?? false,
+    line: resolveThresholdLine(prop.line),
+  };
+}
+
 const BADGE_DEFAULTS: ResolvedBadgeConfig = {
   variant: "default",
   tail: true,