react-native-livechart 4.4.0 → 4.5.0

package/src/components/LiveChart.tsx

@@ -1,10 +1,12 @@
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
-import { View } from "react-native";
+import { StyleSheet, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import {
+import Animated, {
   useAnimatedReaction,
+  useAnimatedStyle,
   useDerivedValue,
   useSharedValue,
+  withTiming,
 } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 
@@ -22,7 +24,11 @@ import {
   vec,
 } from "@shopify/react-native-skia";
 
-import { DEFAULT_ACCENT_COLOR, HOLD_TO_SCRUB_MS } from "../constants";
+import {
+  DEFAULT_ACCENT_COLOR,
+  HOLD_TO_SCRUB_MS,
+  SCRUB_OVERLAY_FADE_MS,
+} from "../constants";
 import {
   resolveAreaDots,
   resolveAxisLabel,
@@ -32,11 +38,13 @@ import {
   resolveGradient,
   resolveGridStyle,
   resolveLeftEdgeFade,
+  resolveLoading,
   resolveMarkerCluster,
   resolveMetrics,
   resolvePulse,
   resolveScrub,
   resolveScrubAction,
+  resolveTransitions,
   resolveReturnToLiveMs,
   resolveSelectionDot,
   resolveThreshold,
@@ -208,6 +216,7 @@ function useLiveChartController({
   timeWindow = 30,
   paused = false,
   loading = false,
+  transitions,
   // `static` is a reserved word — alias it so the destructure parses.
   static: isStatic = false,
   smoothing = 0.08,
@@ -535,7 +544,17 @@ function useLiveChartController({
     candles,
   });
 
-  const reveal = useChartReveal(loading, hasData, isStatic);
+  // Resolve the loading shell: null = not loading, else the styled config (a
+  // non-null result is the "is loading" flag and carries the look).
+  const loadingCfg = resolveLoading(loading);
+  const loadingActive = loadingCfg !== null;
+  const transitionsCfg = resolveTransitions(transitions);
+  const reveal = useChartReveal(
+    loadingActive,
+    hasData,
+    isStatic,
+    transitionsCfg.reveal,
+  );
 
   // After data clears, keep last snapshot until morphT finishes dropping (web parity).
   const { lineEngineData, candlesEngine, liveEngine } =
@@ -594,6 +613,7 @@ function useLiveChartController({
   const { lineGroupOpacity, candleGroupOpacity } = useModeBlend(
     isCandle,
     reveal.lineOpacity,
+    transitionsCfg.mode,
   );
 
   // ── Per-frame derived values ───────────────────────────────────────────
@@ -662,6 +682,9 @@ function useLiveChartController({
     // live value when `followViewEdge` tracks the scrolled-back window.
     engine.edgeValue,
     badgeCfg?.followViewEdge ?? false,
+    // Match the standalone loading squiggle's wave during the reveal morph.
+    loadingCfg?.amplitude,
+    loadingCfg?.speed,
   );
 
   // Area-dots fill shader color as a vec4 (channels 0..1), with the config
@@ -1027,6 +1050,25 @@ function useLiveChartController({
       (selectionDotDuringScrub && crosshair.scrubActive.value ? 0 : 1),
   );
 
+  // Fade the annotation overlays (markers + reference lines) out while scrubbing
+  // when `scrub.hideOverlays` is set. Eased off the scrub-ACTIVE flag — not the
+  // crosshair's edge-proximity fade, which drops to 0 near the live dot and would
+  // resurface the overlays mid-scrub. Only this group opacity animates; the
+  // marker atlas / reference-line draws stay intact (one batched draw each).
+  const fadeOverlaysOnScrub =
+    !isStatic && scrubCfg !== null && scrubCfg.hideOverlaysOnScrub === true;
+  const overlayScrubFade = useDerivedValue(() =>
+    fadeOverlaysOnScrub
+      ? withTiming(crosshair.scrubActive.get() ? 0 : 1, {
+          duration: SCRUB_OVERLAY_FADE_MS,
+        })
+      : 1,
+  );
+  // Markers already fade with the dot reveal; fold the scrub-hide fade in too.
+  const markerGroupOpacity = useDerivedValue(
+    () => reveal.dotOpacity.get() * overlayScrubFade.get(),
+  );
+
   return {
     // passthrough props the render needs
     style,
@@ -1090,6 +1132,11 @@ function useLiveChartController({
     // engine + reveal
     engine,
     reveal,
+    // loading shell styling (null → not loading)
+    loadingLineColor: loadingCfg?.color,
+    loadingStrokeWidth: loadingCfg?.strokeWidth,
+    loadingAmplitude: loadingCfg?.amplitude,
+    loadingSpeed: loadingCfg?.speed,
     // derived render values
     backgroundColor,
     gradientEnd,
@@ -1121,6 +1168,8 @@ function useLiveChartController({
     dotX,
     dotY,
     liveDotOpacity,
+    overlayScrubFade,
+    markerGroupOpacity,
     momentumSV,
     tradeMarkers,
     degenPack,
@@ -1309,6 +1358,8 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     markersActive,
     markersSV,
     markerClusterCfg,
+    markerGroupOpacity,
+    overlayScrubFade,
     renderMarker,
     emptyText,
     metricsCfg,
@@ -1318,6 +1369,10 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     yAxisEntries,
     badgeUsesRightGutter,
     gridStyleCfg,
+    loadingLineColor,
+    loadingStrokeWidth,
+    loadingAmplitude,
+    loadingSpeed,
   } = model;
 
   return (
@@ -1350,21 +1405,24 @@ function ChartStack({ model }: { model: LiveChartModel }) {
 
       {/* Index keys: reference lines are a positional array and two may share
           value + label (e.g. duplicate working orders at the same price), which a
-          content-derived key would collapse to one. */}
-      {allRefLines.map((rl, i) => (
-        <ReferenceLineOverlay
-          key={i}
-          engine={engine}
-          padding={effectivePadding}
-          line={rl}
-          palette={palette}
-          formatValue={formatValue}
-          font={skiaFont}
-          fontProp={fontProp}
-          dragValues={dragValues}
-          index={i}
-        />
-      ))}
+          content-derived key would collapse to one. Wrapped in a fade group so
+          `scrub.hideOverlaysOnScrub` can ease the lines out while scrubbing. */}
+      <Group opacity={overlayScrubFade}>
+        {allRefLines.map((rl, i) => (
+          <ReferenceLineOverlay
+            key={i}
+            engine={engine}
+            padding={effectivePadding}
+            line={rl}
+            palette={palette}
+            formatValue={formatValue}
+            font={skiaFont}
+            fontProp={fontProp}
+            dragValues={dragValues}
+            index={i}
+          />
+        ))}
+      </Group>
 
       {/* Threshold marker line + label (behind the chart line). */}
       {thresholdCfg?.line && (
@@ -1523,7 +1581,7 @@ function ChartStack({ model }: { model: LiveChartModel }) {
       )}
 
       {markersActive && (
-        <Group opacity={reveal.dotOpacity}>
+        <Group opacity={markerGroupOpacity}>
           <MarkerOverlay
             markers={markersSV}
             engine={engine}
@@ -1570,6 +1628,10 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         badgeTail={badgeCfg?.tail ?? true}
         badgeMetrics={metricsCfg.badge}
         emptyMetrics={metricsCfg.emptyState}
+        lineColor={loadingLineColor}
+        lineStrokeWidth={loadingStrokeWidth}
+        waveAmplitude={loadingAmplitude}
+        waveSpeed={loadingSpeed}
       />
     </Group>
   );
@@ -1747,10 +1809,11 @@ function ChartRefBadgeLayer({ model }: { model: LiveChartModel }) {
     skiaFont,
     fontProp,
     degenShakeTransform,
+    overlayScrubFade,
   } = model;
   if (allRefLines.length === 0) return null;
   return (
-    <Group transform={degenShakeTransform}>
+    <Group transform={degenShakeTransform} opacity={overlayScrubFade}>
       {allRefLines.map((rl, i) => (
         <ReferenceLineOverlay
           key={i}
@@ -1853,8 +1916,15 @@ export function LiveChart(props: LiveChartProps) {
     topConnector,
     bottomConnector,
     lineIsLinear,
+    overlayScrubFade,
   } = model;
 
+  // Mirror the Skia overlay fade onto the RN custom-overlay siblings (custom
+  // markers / reference-line tags) so `scrub.hideOverlaysOnScrub` hides them too.
+  const overlayFadeStyle = useAnimatedStyle(() => ({
+    opacity: overlayScrubFade.get(),
+  }));
+
   return (
     <GestureDetector gesture={rootGesture}>
       <View
@@ -1921,33 +1991,47 @@ export function LiveChart(props: LiveChartProps) {
         />
 
         {/* Custom-rendered markers — RN views floated over the canvas (non-Skia),
-            pinned to each marker's live position. Sibling of <Canvas>. */}
+            pinned to each marker's live position. Sibling of <Canvas>. Wrapped in
+            a box-none fade layer so `scrub.hideOverlaysOnScrub` hides them with the
+            Skia markers (the wrapper is full-bleed; children keep their own
+            absolute positions). */}
         {markersActive && renderMarker && (
-          <CustomMarkerOverlay
-            markers={markersSV}
-            renderMarker={renderMarker}
-            engine={engine}
-            padding={effectivePadding}
-            lineData={engine.data}
-            lineLinear={lineIsLinear}
-            cluster={markerClusterCfg}
-          />
+          <Animated.View
+            pointerEvents="box-none"
+            style={[StyleSheet.absoluteFill, overlayFadeStyle]}
+          >
+            <CustomMarkerOverlay
+              markers={markersSV}
+              renderMarker={renderMarker}
+              engine={engine}
+              padding={effectivePadding}
+              lineData={engine.data}
+              lineLinear={lineIsLinear}
+              cluster={markerClusterCfg}
+            />
+          </Animated.View>
         )}
 
         {/* Custom-rendered reference-line tags — RN views floated over the canvas
             (non-Skia), pinned to each Form-A line's value. Sibling of <Canvas>.
-            Built-in Skia tags for these lines are suppressed (no double-draw). */}
+            Built-in Skia tags for these lines are suppressed (no double-draw).
+            Same box-none fade wrapper as the custom markers above. */}
         {renderReferenceLine && allRefLines.length > 0 && (
-          <CustomReferenceLineOverlay
-            lines={allRefLines}
-            renderReferenceLine={renderReferenceLine}
-            custom={refLineCustom}
-            engine={engine}
-            padding={effectivePadding}
-            formatValue={formatValue}
-            dragValues={dragValues}
-            dragActive={dragActive}
-          />
+          <Animated.View
+            pointerEvents="box-none"
+            style={[StyleSheet.absoluteFill, overlayFadeStyle]}
+          >
+            <CustomReferenceLineOverlay
+              lines={allRefLines}
+              renderReferenceLine={renderReferenceLine}
+              custom={refLineCustom}
+              engine={engine}
+              padding={effectivePadding}
+              formatValue={formatValue}
+              dragValues={dragValues}
+              dragActive={dragActive}
+            />
+          </Animated.View>
         )}
 
         {/* Custom scrub tooltip — an RN view floated over the canvas (non-Skia),

package/src/components/LiveChartSeries.tsx

@@ -6,12 +6,14 @@
  */
 import { Canvas, Group } from "@shopify/react-native-skia";
 import { useLayoutEffect, useState } from "react";
-import { View } from "react-native";
+import { StyleSheet, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import {
+import Animated, {
   useAnimatedReaction,
+  useAnimatedStyle,
   useDerivedValue,
   useSharedValue,
+  withTiming,
   type SharedValue,
 } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
@@ -19,6 +21,7 @@ import {
   DEFAULT_ACCENT_COLOR,
   HOLD_TO_SCRUB_MS,
   MAX_MULTI_SERIES,
+  SCRUB_OVERLAY_FADE_MS,
 } from "../constants";
 import {
   lineColorsSignatureFromArray,
@@ -33,12 +36,14 @@ import {
   resolveGridStyle,
   resolveLeftEdgeFade,
   resolveLegend,
+  resolveLoading,
   resolveMarkerCluster,
   resolveMetrics,
   resolveMultiSeriesDot,
   resolveReturnToLiveMs,
   resolveScrub,
   resolveSelectionDot,
+  resolveTransitions,
   resolveXAxis,
   resolveYAxis,
   resolveZoom,
@@ -126,6 +131,7 @@ function useLiveChartSeriesController({
   timeWindow = 30,
   paused = false,
   loading = false,
+  transitions,
   smoothing = 0.08,
   exaggerate = false,
   nonNegative = false,
@@ -289,7 +295,18 @@ function useLiveChartSeriesController({
     return false;
   });
 
-  const reveal = useChartReveal(loading, hasData);
+  // Resolve the loading shell: null = not loading, else the styled config.
+  const loadingCfg = resolveLoading(loading);
+  const loadingActive = loadingCfg !== null;
+  // Multi-series is always lines, so only the reveal transition applies (no
+  // candle↔line crossfade); `transitions.mode` is accepted but inert here.
+  const transitionsCfg = resolveTransitions(transitions);
+  const reveal = useChartReveal(
+    loadingActive,
+    hasData,
+    false,
+    transitionsCfg.reveal,
+  );
 
   const effectiveSeries = useMultiSeriesReverseMorphInputs({
     series,
@@ -453,6 +470,23 @@ function useLiveChartSeriesController({
 
   const backgroundColor = `rgb(${palette.bgRgb[0]}, ${palette.bgRgb[1]}, ${palette.bgRgb[2]})`;
 
+  // Fade markers + reference lines out while scrubbing when
+  // `scrub.hideOverlaysOnScrub` is set. Eased off the scrub-ACTIVE flag (not the
+  // crosshair edge fade, which would resurface them near the live dot); only a
+  // group opacity animates — the overlay draws stay intact. See `LiveChart`.
+  const fadeOverlaysOnScrub =
+    scrubCfg !== null && scrubCfg.hideOverlaysOnScrub === true;
+  const overlayScrubFade = useDerivedValue(() =>
+    fadeOverlaysOnScrub
+      ? withTiming(crosshair.scrubActive.get() ? 0 : 1, {
+          duration: SCRUB_OVERLAY_FADE_MS,
+        })
+      : 1,
+  );
+  const markerGroupOpacity = useDerivedValue(
+    () => reveal.dotOpacity.get() * overlayScrubFade.get(),
+  );
+
   return {
     // passthrough props the render needs
     series,
@@ -484,6 +518,11 @@ function useLiveChartSeriesController({
     // engine + reveal
     engine,
     reveal,
+    // loading shell styling (null → not loading)
+    loadingLineColor: loadingCfg?.color,
+    loadingStrokeWidth: loadingCfg?.strokeWidth,
+    loadingAmplitude: loadingCfg?.amplitude,
+    loadingSpeed: loadingCfg?.speed,
     effectiveSeries,
     layoutHeight,
     onLayout,
@@ -500,6 +539,8 @@ function useLiveChartSeriesController({
     markersActive,
     markersSV,
     markerClusterCfg,
+    markerGroupOpacity,
+    overlayScrubFade,
     renderMarker,
     // selection dot: resolved config + fallback color (the leading series' color)
     selectionDot: selectionDotCfg,
@@ -545,10 +586,16 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
     markersActive,
     markersSV,
     markerClusterCfg,
+    markerGroupOpacity,
+    overlayScrubFade,
     renderMarker,
     series,
     emptyText,
     metricsCfg,
+    loadingLineColor,
+    loadingStrokeWidth,
+    loadingAmplitude,
+    loadingSpeed,
   } = model;
 
   return (
@@ -570,18 +617,21 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
 
       {/* Index keys: reference lines are a positional array and two may share
           value + label (e.g. duplicate working orders at the same price), which a
-          content-derived key would collapse to one. */}
-      {allRefLines.map((rl, i) => (
-        <ReferenceLineOverlay
-          key={i}
-          engine={engine}
-          padding={effectivePadding}
-          line={rl}
-          palette={palette}
-          formatValue={formatValue}
-          font={skiaFont}
-        />
-      ))}
+          content-derived key would collapse to one. Fade group lets
+          `scrub.hideOverlaysOnScrub` ease the lines out while scrubbing. */}
+      <Group opacity={overlayScrubFade}>
+        {allRefLines.map((rl, i) => (
+          <ReferenceLineOverlay
+            key={i}
+            engine={engine}
+            padding={effectivePadding}
+            line={rl}
+            palette={palette}
+            formatValue={formatValue}
+            font={skiaFont}
+          />
+        ))}
+      </Group>
 
       {dotCfg.valueLine && (
         <Group opacity={reveal.lineOpacity}>
@@ -654,7 +704,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
       )}
 
       {markersActive && (
-        <Group opacity={reveal.dotOpacity}>
+        <Group opacity={markerGroupOpacity}>
           <MarkerOverlay
             markers={markersSV}
             engine={engine}
@@ -680,6 +730,10 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
         strokeWidth={strokeWidth}
         badge={false}
         emptyMetrics={metricsCfg.emptyState}
+        lineColor={loadingLineColor}
+        lineStrokeWidth={loadingStrokeWidth}
+        waveAmplitude={loadingAmplitude}
+        waveSpeed={loadingSpeed}
       />
     </Group>
   );
@@ -726,10 +780,11 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
     formatValue,
     skiaFont,
     degenShakeTransform,
+    overlayScrubFade,
   } = model;
   if (allRefLines.length === 0) return null;
   return (
-    <Group transform={degenShakeTransform}>
+    <Group transform={degenShakeTransform} opacity={overlayScrubFade}>
       {allRefLines.map((rl, i) => (
         <ReferenceLineOverlay
           key={i}
@@ -778,8 +833,15 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     markersSV,
     markerClusterCfg,
     renderMarker,
+    overlayScrubFade,
   } = model;
 
+  // Mirror the Skia overlay fade onto the RN custom-marker sibling so
+  // `scrub.hideOverlaysOnScrub` hides it with the Skia markers.
+  const overlayFadeStyle = useAnimatedStyle(() => ({
+    opacity: overlayScrubFade.get(),
+  }));
+
   // Extend the scrub dim past the plot's right edge to fully cover the series
   // dots (with their halo) and pulse rings, all centered on that edge. The
   // gutter reserves room beyond this for the value/Y-axis labels, drawn on top.
@@ -876,16 +938,23 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
           />
 
           {/* Custom-rendered markers — RN views floated over the canvas
-              (non-Skia), pinned to each marker's live position. */}
+              (non-Skia), pinned to each marker's live position. Box-none fade
+              wrapper so `scrub.hideOverlaysOnScrub` hides them with the Skia
+              markers (full-bleed; children keep their own absolute positions). */}
           {markersActive && renderMarker && (
-            <CustomMarkerOverlay
-              markers={markersSV}
-              renderMarker={renderMarker}
-              engine={engine}
-              padding={effectivePadding}
-              series={series}
-              cluster={markerClusterCfg}
-            />
+            <Animated.View
+              pointerEvents="box-none"
+              style={[StyleSheet.absoluteFill, overlayFadeStyle]}
+            >
+              <CustomMarkerOverlay
+                markers={markersSV}
+                renderMarker={renderMarker}
+                engine={engine}
+                padding={effectivePadding}
+                series={series}
+                cluster={markerClusterCfg}
+              />
+            </Animated.View>
           )}
         </View>
       </GestureDetector>

package/src/components/LoadingOverlay.tsx

@@ -62,6 +62,10 @@ export function LoadingOverlay({
   badgeTail = true,
   badgeMetrics = BADGE_METRICS_DEFAULTS,
   emptyMetrics = EMPTY_STATE_METRICS_DEFAULTS,
+  lineColor,
+  lineStrokeWidth,
+  waveAmplitude = 14,
+  waveSpeed = 1,
 }: {
   engine: ChartEngineLayout;
   padding: ChartPadding;
@@ -73,6 +77,14 @@ export function LoadingOverlay({
   isEmpty: SharedValue<boolean> | { value: boolean };
   emptyText: string;
   strokeWidth: number;
+  /** Loading squiggle + skeleton color. Omit → theme `gridLine`. */
+  lineColor?: string;
+  /** Loading squiggle stroke width. Omit → `strokeWidth`. */
+  lineStrokeWidth?: number;
+  /** Breathing-wave base amplitude (px). */
+  waveAmplitude?: number;
+  /** Breathing-wave speed multiplier. */
+  waveSpeed?: number;
   /** Mirror the badge prop so labels align with GridOverlay's label positions. */
   badge?: boolean;
   /** Whether the badge tail spike is shown; affects the left inset used for skeleton alignment. */
@@ -86,6 +98,11 @@ export function LoadingOverlay({
   const leftInset =
     badgeMetrics.dotGap + badgeTailAndCap(font.getSize(), badgeTail, badgeMetrics);
 
+  // Loading-shell color (squiggle + skeleton placeholders) and squiggle stroke,
+  // both overridable via `loading={{ color, strokeWidth }}`.
+  const loadingColor = lineColor ?? palette.gridLine;
+  const loadingStroke = lineStrokeWidth ?? strokeWidth;
+
   // Squiggly path — built into a reused PathBuilder and detach()-ed each frame.
   const squigglyBuilder = usePathBuilder();
 
@@ -100,6 +117,8 @@ export function LoadingOverlay({
       engine.canvasHeight.get(),
       padding,
       engine.timestamp.get(),
+      waveAmplitude,
+      waveSpeed,
     );
     return buildSplineDetached(b, pts);
   });
@@ -225,8 +244,8 @@ export function LoadingOverlay({
       <Path
         path={squigglyPath}
         style="stroke"
-        strokeWidth={strokeWidth}
-        color={palette.gridLine}
+        strokeWidth={loadingStroke}
+        color={loadingColor}
         strokeCap="round"
         strokeJoin="round"
       />
@@ -255,7 +274,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
       <RoundedRect
         x={lx}
@@ -263,7 +282,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
       <RoundedRect
         x={lx}
@@ -271,7 +290,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
       <RoundedRect
         x={lx}
@@ -279,7 +298,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
 
       {/* Empty state label */}

package/src/constants.ts

@@ -31,6 +31,23 @@ export const HOLD_TO_SCRUB_MS = 500;
  */
 export const RETURN_TO_LIVE_MS = 450;
 
+/**
+ * Duration (ms) of the fade applied to annotation overlays (markers + reference
+ * lines) when `scrub.hideOverlaysOnScrub` is on — how long they take to ease out as a
+ * scrub starts and back in on release. Driven by the scrub-active flag, eased on
+ * the UI thread. Shared by `LiveChart` and `LiveChartSeries`.
+ */
+export const SCRUB_OVERLAY_FADE_MS = 150;
+
+/**
+ * Base wave amplitude (px) of the breathing loading squiggle — it breathes
+ * between `0.4×` and `1.0×` this. Overridable via `loading={{ amplitude }}`.
+ */
+export const LOADING_WAVE_AMPLITUDE = 14;
+
+/** Default breathing-wave speed multiplier (`1` = built-in cadence). */
+export const LOADING_WAVE_SPEED = 1;
+
 // ─── Metric default tokens (single source of truth for LiveChartMetrics) ─────
 // The resolved `metrics` config (see resolveMetrics) is assembled from these
 // objects. Draw/worklet helpers default their metric params to the matching