react-native-livechart 4.20.0 → 4.21.1

package/src/components/ReferenceLineOverlay.tsx

@@ -18,8 +18,12 @@ import {
   type ReferenceLineLayout,
 } from "../hooks/useReferenceLine";
 import { MONO_FONT_FAMILY } from "../lib/monoFontFamily";
-import { referenceLineForm, resolveReferenceBadge } from "../math/referenceLines";
+import {
+  referenceLineForm,
+  resolveReferenceBadge,
+} from "../math/referenceLines";
 import type { FontConfig, LiveChartPalette, ReferenceLine } from "../types";
+import { ReferenceLineSeriesOverlay } from "./ReferenceLineSeriesOverlay";
 
 /** Translucent fill alpha for value / time bands. */
 const BAND_FILL_OPACITY = 0.16;
@@ -33,9 +37,10 @@ const CONNECTOR_GAP = 4;
 const BADGE_EDGE_INSET = 2;
 
 /**
- * Renders one reference line or band into the chart canvas. Handles all three
- * `ReferenceLine` forms (horizontal line, horizontal value band, vertical time
- * band) plus the Form-A pill badge (in-range tag + off-screen chevron pin).
+ * Renders one reference line or band into the chart canvas. Handles all four
+ * `ReferenceLine` forms (horizontal line, time-varying line, horizontal value
+ * band, vertical time band) plus the Form-A pill badge (in-range tag +
+ * off-screen chevron pin).
  * Self-contained so callers can `.map()` over a variable-length array.
  */
 type ReferenceLineOverlayProps = {
@@ -63,7 +68,7 @@ type ReferenceLineOverlayProps = {
    * this line — used when a custom `renderReferenceLine` element owns the tag.
    * The line / band stroke and a badged line's dashed connector still draw. No
    * effect on the base pass.
-  */
+   */
   suppressTag?: boolean;
   /**
    * Suppress the built-in tag only while the line is off-axis. Used by
@@ -94,7 +99,74 @@ type ReferenceLineOverlayProps = {
   gridEndGap?: number;
 };
 
-export function ReferenceLineOverlay({
+/**
+ * Dispatch to the series or scalar/band renderer without mixing their hook
+ * lifecycles. A stable `id` may therefore switch forms safely across renders.
+ */
+export function ReferenceLineOverlay(props: ReferenceLineOverlayProps) {
+  if (referenceLineForm(props.line) === "series") {
+    return (
+      <ReferenceLineSeriesOverlay
+        engine={props.engine}
+        padding={props.padding}
+        line={props.line}
+        palette={props.palette}
+        formatValue={props.formatValue}
+        font={props.font}
+        badgeLayer={props.badgeLayer ?? false}
+      />
+    );
+  }
+  return <ReferenceLineStaticOverlay {...props} />;
+}
+
+function resolveStaticReferenceLineAppearance(
+  line: ReferenceLine,
+  palette: LiveChartPalette,
+  fontProp: FontConfig | undefined,
+) {
+  const form = referenceLineForm(line);
+  const isBand = form === "value-band" || form === "time-band";
+  const color = line.color ?? palette.refLine;
+  const badge = resolveReferenceBadge(line);
+  const badgeHasFontOverride =
+    badge != null &&
+    (badge.fontSize != null ||
+      badge.fontFamily != null ||
+      badge.fontWeight != null);
+
+  return {
+    form,
+    isBand,
+    color,
+    fillColor: line.fillColor ?? color,
+    strokeOpacity: Math.max(0, Math.min(1, line.strokeOpacity ?? 1)),
+    badge,
+    badgeHasFontOverride,
+    badgeFontConfig: badgeHasFontOverride
+      ? {
+          ...fontProp,
+          fontFamily: badge?.fontFamily ?? fontProp?.fontFamily,
+          fontSize: badge?.fontSize ?? fontProp?.fontSize,
+          fontWeight: badge?.fontWeight ?? fontProp?.fontWeight,
+        }
+      : fontProp,
+    labelColor:
+      badge?.textColor ?? line.labelColor ?? line.color ?? palette.refLabel,
+    strokeWidth: line.strokeWidth ?? 1,
+    intervals: line.intervals ?? [4, 4],
+    bandFillOpacity: line.fillOpacity ?? BAND_FILL_OPACITY,
+    hasBandBorder: isBand && line.strokeWidth !== undefined,
+    badgeBackground: badge?.background ?? palette.tooltipBg,
+    badgeBorderColor: badge?.borderColor ?? color,
+    badgeBorderWidth: badge?.borderWidth ?? 1,
+    badgeRadius: badge?.radius ?? BADGE_PILL_RADIUS,
+    badgeOffsetX: badge?.offsetX ?? 0,
+    badgeOffsetY: badge?.offsetY ?? 0,
+  };
+}
+
+function ReferenceLineStaticOverlay({
   engine,
   padding,
   line,
@@ -113,31 +185,30 @@ export function ReferenceLineOverlay({
   labelRightMargin,
   gridEndGap,
 }: ReferenceLineOverlayProps) {
-  const form = referenceLineForm(line);
-  const isBand = form === "value-band" || form === "time-band";
-
-  const color = line.color ?? palette.refLine;
-
-  // Resolved badge appearance (badge config → fallback flat fields → theme).
-  const badge = resolveReferenceBadge(line);
+  const {
+    form,
+    isBand,
+    color,
+    fillColor,
+    strokeOpacity,
+    badge,
+    badgeHasFontOverride,
+    badgeFontConfig,
+    labelColor,
+    strokeWidth,
+    intervals,
+    bandFillOpacity,
+    hasBandBorder,
+    badgeBackground,
+    badgeBorderColor,
+    badgeBorderWidth,
+    badgeRadius,
+    badgeOffsetX,
+    badgeOffsetY,
+  } = resolveStaticReferenceLineAppearance(line, palette, fontProp);
 
-  // Per-badge font (size/family/weight) override; reuses the chart `font` when no
-  // badge font knob is set, so plain lines and gutter labels are unchanged. The
-  // built font drives pill measurement (via useReferenceLine) and the badge text.
-  const badgeHasFontOverride =
-    badge != null &&
-    (badge.fontSize != null ||
-      badge.fontFamily != null ||
-      badge.fontWeight != null);
   const badgeFontOverride = useChartSkiaFont(
-    badgeHasFontOverride
-      ? {
-          ...fontProp,
-          fontFamily: badge?.fontFamily ?? fontProp?.fontFamily,
-          fontSize: badge?.fontSize ?? fontProp?.fontSize,
-          fontWeight: badge?.fontWeight ?? fontProp?.fontWeight,
-        }
-      : fontProp,
+    badgeFontConfig,
     MONO_FONT_FAMILY,
     palette.labelFontSize,
   );
@@ -157,32 +228,13 @@ export function ReferenceLineOverlay({
     font,
   );
 
-  const labelColor =
-    badge?.textColor ?? line.labelColor ?? line.color ?? palette.refLabel;
-  const strokeWidth = line.strokeWidth ?? 1;
-  const intervals = line.intervals ?? [4, 4];
-
-  // Band fill + optional dashed border (border only when strokeWidth is set).
-  const bandFillOpacity = line.fillOpacity ?? BAND_FILL_OPACITY;
-  const hasBandBorder = isBand && line.strokeWidth !== undefined;
-
-  const badgeBackground = badge?.background ?? palette.tooltipBg;
-  const badgeBorderColor = badge?.borderColor ?? color;
-  const badgeBorderWidth = badge?.borderWidth ?? 1;
-  const badgeRadius = badge?.radius ?? BADGE_PILL_RADIUS;
-  // Nudge the whole badge (connector + pill + chevron + icon + label) off its anchor.
-  const badgeOffsetX = badge?.offsetX ?? 0;
-  const badgeOffsetY = badge?.offsetY ?? 0;
-  const badgeTransform =
-    badgeOffsetX !== 0 || badgeOffsetY !== 0
-      ? [{ translateX: badgeOffsetX }, { translateY: badgeOffsetY }]
-      : undefined;
-
   if (!badgeLayer) {
     return (
       <ReferenceLineBasePass
         layout={layout}
         color={color}
+        fillColor={fillColor}
+        strokeOpacity={strokeOpacity}
         strokeWidth={strokeWidth}
         intervals={intervals}
         isBand={isBand}
@@ -221,6 +273,8 @@ export function ReferenceLineOverlay({
 function ReferenceLineBasePass({
   layout,
   color,
+  fillColor,
+  strokeOpacity,
   strokeWidth,
   intervals,
   isBand,
@@ -230,6 +284,8 @@ function ReferenceLineBasePass({
 }: {
   layout: SharedValue<ReferenceLineLayout>;
   color: string;
+  fillColor: string;
+  strokeOpacity: number;
   strokeWidth: number;
   intervals: [number, number];
   isBand: boolean;
@@ -282,20 +338,20 @@ function ReferenceLineBasePass({
   });
   const lineOpacity = useDerivedValue(() => {
     const l = layout.get();
-    return l.visible && l.drawLine && !isBand ? 1 : 0;
+    return l.visible && l.drawLine && !isBand ? strokeOpacity : 0;
   });
   const bandOpacity = useDerivedValue(() =>
     layout.get().visible && isBand ? bandFillOpacity : 0,
   );
   const bandBorderOpacity = useDerivedValue(() =>
-    layout.get().visible && hasBandBorder ? 1 : 0,
+    layout.get().visible && hasBandBorder ? strokeOpacity : 0,
   );
 
   return (
     <Group>
       {isBand && (
         <Group opacity={bandOpacity}>
-          <Path path={bandPath} style="fill" color={color} />
+          <Path path={bandPath} style="fill" color={fillColor} />
         </Group>
       )}
       {hasBandBorder && (
@@ -381,7 +437,7 @@ function ReferenceLineBadgePass({
       const customTagActive =
         suppressTag || (suppressTagWhenOffAxis && l.offAxis);
       const customWidth = customTagActive
-        ? customTagWidths?.get()[index] ?? 0
+        ? (customTagWidths?.get()[index] ?? 0)
         : 0;
       if (customWidth > 0) {
         if (badgePosition === "left") {
@@ -435,7 +491,9 @@ function ReferenceLineBadgePass({
     const grouped = groupHidden ? groupHidden.get()[index] === true : false;
     const customTagActive =
       suppressTag || (suppressTagWhenOffAxis && l.offAxis);
-    return !customTagActive && !grouped && l.visible && l.label.length > 0 ? 1 : 0;
+    return !customTagActive && !grouped && l.visible && l.label.length > 0
+      ? 1
+      : 0;
   });
   const iconOpacity = useDerivedValue(() => {
     const l = layout.get();

package/src/components/ReferenceLineSeriesOverlay.tsx

@@ -0,0 +1,141 @@
+import {
+  DashPathEffect,
+  Group,
+  Path,
+  Text as SkiaText,
+  type SkFont,
+} from "@shopify/react-native-skia";
+import { useDerivedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { usePathBuilder } from "../hooks/usePathBuilder";
+import { useReferenceLineSeries } from "../hooks/useReferenceLineSeries";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import { thresholdDashPhase } from "../math/threshold";
+import type { LiveChartPalette, ReferenceLine } from "../types";
+
+/**
+ * Draws Form-B `ReferenceLine.series` geometry. The base pass is a clipped Skia
+ * polyline behind the chart; the badge pass is the live-edge label above the
+ * chart fade, matching the existing two-pass reference-line layering.
+ */
+export function ReferenceLineSeriesOverlay({
+  engine,
+  padding,
+  line,
+  palette,
+  formatValue,
+  font,
+  badgeLayer,
+}: {
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  line: ReferenceLine;
+  palette: LiveChartPalette;
+  formatValue: (value: number) => string;
+  font: SkFont;
+  badgeLayer: boolean;
+}) {
+  const points = line.series ?? [];
+  const extendToNow = line.extendToNow ?? true;
+  const geometry = useReferenceLineSeries(
+    engine,
+    padding,
+    points,
+    extendToNow,
+  );
+  const color = line.color ?? palette.refLine;
+  const labelColor = line.labelColor ?? line.color ?? palette.refLabel;
+  const strokeOpacity = Math.max(0, Math.min(1, line.strokeOpacity ?? 1));
+  const strokeWidth = line.strokeWidth ?? 1;
+  const intervals = line.intervals ?? [4, 4];
+  const dashCycle = intervals[0] + intervals[1];
+
+  const builder = usePathBuilder();
+  const path = useDerivedValue(() => {
+    const b = builder.value;
+    const screen = geometry.screenPts.get();
+    if (geometry.visible.get() && screen.length >= 4) {
+      b.moveTo(screen[0], screen[1]);
+      for (let i = 2; i < screen.length; i += 2) {
+        b.lineTo(screen[i], screen[i + 1]);
+      }
+    }
+    return b.detach();
+  });
+  const pathOpacity = useDerivedValue(() =>
+    geometry.visible.get() ? strokeOpacity : 0,
+  );
+  const dashPhase = useDerivedValue(() =>
+    thresholdDashPhase(
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+      padding.left,
+      engine.canvasWidth.get() - padding.right,
+      dashCycle,
+    ),
+  );
+  const plotClip = useDerivedValue(() => ({
+    x: padding.left,
+    y: padding.top,
+    width: Math.max(0, engine.canvasWidth.get() - padding.left - padding.right),
+    height: Math.max(
+      0,
+      engine.canvasHeight.get() - padding.top - padding.bottom,
+    ),
+  }));
+
+  const metrics = font.getMetrics();
+  const baselineOffset = (metrics.ascent + metrics.descent) / 2;
+  const labelText = useDerivedValue(() => {
+    const value = formatValue(geometry.currentValue.get());
+    if (line.label) return line.showValue ? `${line.label} ${value}` : line.label;
+    return value;
+  });
+  const labelX = useDerivedValue(() => {
+    const left = padding.left;
+    const right = engine.canvasWidth.get() - padding.right;
+    const position = line.labelPosition ?? "right";
+    if (position === "left") return left + 4;
+    if (position === "center") {
+      return (left + right) / 2 - measureFontTextWidth(font, labelText.get()) / 2;
+    }
+    return right + 4;
+  });
+  const labelY = useDerivedValue(
+    () => geometry.currentY.get() - baselineOffset,
+  );
+  const labelOpacity = useDerivedValue(() =>
+    geometry.currentVisible.get() ? 1 : 0,
+  );
+
+  if (badgeLayer) {
+    return (
+      <Group opacity={labelOpacity}>
+        <SkiaText
+          x={labelX}
+          y={labelY}
+          text={labelText}
+          font={font}
+          color={labelColor}
+        />
+      </Group>
+    );
+  }
+
+  return (
+    <Group clip={plotClip} opacity={pathOpacity}>
+      <Path
+        path={path}
+        style="stroke"
+        strokeWidth={strokeWidth}
+        strokeCap="round"
+        strokeJoin="round"
+        color={color}
+      >
+        <DashPathEffect intervals={intervals} phase={dashPhase} />
+      </Path>
+    </Group>
+  );
+}

package/src/core/chartDataPresence.ts

@@ -0,0 +1,24 @@
+import type { CandlePoint, LiveChartPoint, SeriesConfig } from "../types";
+
+/** A single historical line sample is enough to anchor the live tip. */
+export function hasLineChartData(points: LiveChartPoint[]): boolean {
+  "worklet";
+  return points.length > 0;
+}
+
+/** A single committed OHLC bucket is drawable as a candle. */
+export function hasCandleChartData(
+  candles: CandlePoint[] | undefined,
+): boolean {
+  "worklet";
+  return (candles?.length ?? 0) > 0;
+}
+
+/** Multi-series charts are non-empty when any series has one sample. */
+export function hasMultiSeriesChartData(series: SeriesConfig[]): boolean {
+  "worklet";
+  for (let i = 0; i < series.length; i++) {
+    if (series[i].data.length > 0) return true;
+  }
+  return false;
+}

package/src/core/liveChartEngineTick.ts

@@ -1,8 +1,9 @@
-import type { CandlePoint, LiveChartPoint } from "../types";
+import type { CandleGap, CandlePoint, LiveChartPoint } from "../types";
 
 import { MOTION_METRICS_DEFAULTS } from "../constants";
 import { lerp } from "../math/lerp";
 import { thresholdRangeMinMax } from "../math/threshold";
+import { previousCandleCloseAtTime } from "../math/candleGaps";
 
 /** Scratch for the threshold range fold — only alive within one tick call. */
 const THRESHOLD_RANGE_SCRATCH: [number, number] = [0, 0];
@@ -131,6 +132,11 @@ export interface EngineTickInput {
   candles?: CandlePoint[];
   /** In-progress candle. Included in Y range when mode is `"candle"`. */
   liveCandle?: CandlePoint | null;
+  /** Explicit semantic gaps used only for previous-close range anchoring. */
+  candleGaps?: CandleGap[];
+  candleGapBridgeNoTrades?: boolean;
+  candleGapBridgeUnavailable?: boolean;
+  candleGapBridgeUnknown?: boolean;
 }
 
 /**
@@ -303,6 +309,33 @@ export function tickLiveChartEngineFrame(
   state.extremaMinTime = hasMin ? minTime : NaN;
   state.extremaMaxTime = hasMax ? maxTime : NaN;
 
+  // A previous-close bridge is presentation, not a traded observation: include
+  // its anchor in the fitted range (so a viewport parked wholly inside an outage
+  // stays framed correctly) only after snapshotting the real-data extrema above.
+  if (input.mode === "candle" && input.candleGaps) {
+    const cs = input.candles ?? [];
+    const lc = input.liveCandle ?? null;
+    for (let i = 0; i < input.candleGaps.length; i++) {
+      const gap = input.candleGaps[i];
+      if (gap.from >= state.timestamp || gap.to <= winStart) continue;
+      const bridge =
+        gap.kind === "no-trades"
+          ? input.candleGapBridgeNoTrades
+          : gap.kind === "unavailable"
+            ? input.candleGapBridgeUnavailable
+            : input.candleGapBridgeUnknown;
+      if (!bridge) continue;
+      const anchor = previousCandleCloseAtTime(
+        cs,
+        lc,
+        Math.min(gap.to, state.timestamp),
+      );
+      if (anchor === null) continue;
+      if (anchor < tMin) tMin = anchor;
+      if (anchor > tMax) tMax = anchor;
+    }
+  }
+
   // Keep the animated live tip inside the range — but only while it's actually
   // in the window. Scrolled back, the live value sits beyond the frozen right
   // edge; folding it in would pin the Y range to the live price and stop the

package/src/core/resolveConfig.ts

@@ -3,6 +3,12 @@ import type {
   AxisLabelConfig,
   BadgeConfig,
   BadgeVariant,
+  CandleGap,
+  CandleGapBandStyle,
+  CandleGapBridgeStyle,
+  CandleGapKind,
+  CandleGapLabelStyle,
+  CandleGapsConfig,
   DegenOptions,
   FontConfig,
   FontWeight,
@@ -114,6 +120,38 @@ export interface ResolvedVolumeConfig {
   opacity: number;
 }
 
+export interface ResolvedCandleGapBridgeStyle {
+  color: string | undefined;
+  opacity: number;
+  strokeWidth: number;
+  strokeCap: "butt" | "round" | "square";
+}
+
+export interface ResolvedCandleGapBandStyle {
+  fillColor: string | undefined;
+  fillOpacity: number;
+  borderColor: string | undefined;
+  borderOpacity: number;
+  borderWidth: number;
+  intervals: [number, number];
+}
+
+export interface ResolvedCandleGapLabelStyle {
+  color: string | undefined;
+  position: "left" | "right";
+}
+
+export interface ResolvedCandleGapStyle {
+  bridge: ResolvedCandleGapBridgeStyle | null;
+  band: ResolvedCandleGapBandStyle | null;
+  label: ResolvedCandleGapLabelStyle | null;
+}
+
+export interface ResolvedCandleGapsConfig {
+  gaps: CandleGap[];
+  styles: Record<CandleGapKind, ResolvedCandleGapStyle>;
+}
+
 /** Resolved straight-line styling (connector, etc.). `color: undefined` → caller default. */
 export interface ResolvedLineStyleConfig {
   color: string | undefined;
@@ -379,6 +417,8 @@ export interface ResolvedThresholdLineConfig {
   label: string | undefined;
   /** Label side; `"left"` sits inside the plot (clear of the y-axis gutter). */
   labelPosition: "left" | "right";
+  /** Series badge value/Y source; `"last"` preserves the live-edge default. */
+  labelAnchor: "first" | "last";
   /** undefined → use palette.refLine (line) / palette.refLabel (label) at render time. */
   color: string | undefined;
   intervals: [number, number];
@@ -415,6 +455,7 @@ export interface ResolvedThresholdConfig {
 const THRESHOLD_LINE_DEFAULTS: ResolvedThresholdLineConfig = {
   label: undefined,
   labelPosition: "left",
+  labelAnchor: "last",
   color: undefined,
   intervals: [4, 4],
   strokeWidth: 1,
@@ -535,6 +576,151 @@ export function resolveVolume(
   return resolveToggle(prop, VOLUME_DEFAULTS, false);
 }
 
+const CANDLE_GAP_BRIDGE_DEFAULTS: ResolvedCandleGapBridgeStyle = {
+  color: undefined,
+  opacity: 0.7,
+  strokeWidth: 2,
+  strokeCap: "round",
+};
+
+const CANDLE_GAP_BAND_DEFAULTS: ResolvedCandleGapBandStyle = {
+  fillColor: undefined,
+  fillOpacity: 0.12,
+  borderColor: undefined,
+  borderOpacity: 1,
+  borderWidth: 2,
+  intervals: [4, 4],
+};
+
+const CANDLE_GAP_LABEL_DEFAULTS: ResolvedCandleGapLabelStyle = {
+  color: undefined,
+  position: "left",
+};
+
+function clampOpacity(value: number): number {
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+
+const CANDLE_GAP_STYLE_DEFAULTS: Record<CandleGapKind, ResolvedCandleGapStyle> = {
+  "no-trades": {
+    bridge: CANDLE_GAP_BRIDGE_DEFAULTS,
+    band: null,
+    label: null,
+  },
+  unavailable: {
+    bridge: { ...CANDLE_GAP_BRIDGE_DEFAULTS, opacity: 0.55 },
+    band: CANDLE_GAP_BAND_DEFAULTS,
+    label: CANDLE_GAP_LABEL_DEFAULTS,
+  },
+  unknown: {
+    bridge: null,
+    band: {
+      ...CANDLE_GAP_BAND_DEFAULTS,
+      fillOpacity: 0.08,
+      borderWidth: 1,
+    },
+    label: CANDLE_GAP_LABEL_DEFAULTS,
+  },
+};
+
+function resolveCandleGapBridge(
+  override: false | CandleGapBridgeStyle | undefined,
+  semanticDefault: ResolvedCandleGapBridgeStyle | null,
+): ResolvedCandleGapBridgeStyle | null {
+  if (override === false) return null;
+  if (override === undefined) {
+    return semanticDefault ? { ...semanticDefault } : null;
+  }
+  const base = semanticDefault ?? CANDLE_GAP_BRIDGE_DEFAULTS;
+  const strokeCap = override.strokeCap;
+  return {
+    color: override.color ?? base.color,
+    opacity: clampOpacity(override.opacity ?? base.opacity),
+    strokeWidth: Math.max(0, override.strokeWidth ?? base.strokeWidth),
+    strokeCap:
+      strokeCap === "butt" || strokeCap === "round" || strokeCap === "square"
+        ? strokeCap
+        : base.strokeCap,
+  };
+}
+
+function resolveCandleGapBand(
+  override: false | CandleGapBandStyle | undefined,
+  semanticDefault: ResolvedCandleGapBandStyle | null,
+): ResolvedCandleGapBandStyle | null {
+  if (override === false) return null;
+  if (override === undefined) {
+    return semanticDefault ? { ...semanticDefault } : null;
+  }
+  const base = semanticDefault ?? CANDLE_GAP_BAND_DEFAULTS;
+  return {
+    fillColor: override.fillColor ?? base.fillColor,
+    fillOpacity: clampOpacity(override.fillOpacity ?? base.fillOpacity),
+    borderColor: override.borderColor ?? base.borderColor,
+    borderOpacity: clampOpacity(override.borderOpacity ?? base.borderOpacity),
+    borderWidth: Math.max(0, override.borderWidth ?? base.borderWidth),
+    intervals: override.intervals ?? base.intervals,
+  };
+}
+
+function resolveCandleGapLabel(
+  override: false | CandleGapLabelStyle | undefined,
+  semanticDefault: ResolvedCandleGapLabelStyle | null,
+): ResolvedCandleGapLabelStyle | null {
+  if (override === false) return null;
+  if (override === undefined) {
+    return semanticDefault ? { ...semanticDefault } : null;
+  }
+  const base = semanticDefault ?? CANDLE_GAP_LABEL_DEFAULTS;
+  return {
+    color: override.color ?? base.color,
+    position:
+      override.position === "left" || override.position === "right"
+        ? override.position
+        : base.position,
+  };
+}
+
+/** Resolve and defensively normalize explicit candle-gap metadata. */
+export function resolveCandleGaps(
+  prop: CandleGap[] | CandleGapsConfig | undefined,
+): ResolvedCandleGapsConfig | null {
+  if (prop == null) return null;
+  const gaps = (Array.isArray(prop) ? prop : prop.gaps)
+    .filter(
+      (gap) =>
+        Number.isFinite(gap.from) &&
+        Number.isFinite(gap.to) &&
+        gap.to > gap.from &&
+        (gap.kind === "no-trades" ||
+          gap.kind === "unavailable" ||
+          gap.kind === "unknown"),
+    )
+    .slice()
+    .sort((a, b) => a.from - b.from || a.to - b.to);
+  if (gaps.length === 0) return null;
+
+  const overrides = Array.isArray(prop) ? undefined : prop.styles;
+  const resolveStyle = (kind: CandleGapKind): ResolvedCandleGapStyle => {
+    const base = CANDLE_GAP_STYLE_DEFAULTS[kind];
+    const override = overrides?.[kind];
+    return {
+      bridge: resolveCandleGapBridge(override?.bridge, base.bridge),
+      band: resolveCandleGapBand(override?.band, base.band),
+      label: resolveCandleGapLabel(override?.label, base.label),
+    };
+  };
+
+  return {
+    gaps,
+    styles: {
+      "no-trades": resolveStyle("no-trades"),
+      unavailable: resolveStyle("unavailable"),
+      unknown: resolveStyle("unknown"),
+    },
+  };
+}
+
 export interface ResolvedZoomConfig {
   /** Tightest window (max zoom-in), seconds. `undefined` → `timeWindow / 8`. */
   minTimeWindow: number | undefined;