@ledgerhq/lumen-ui-rnative-visualization 0.1.13 → 0.1.15

package/src/lib/Components/Scrubber/Scrubber.tsx

@@ -8,26 +8,26 @@ import {
   LinearGradient,
   Rect,
   Stop,
-  Text as SvgText,
 } from 'react-native-svg';
 
 import { useCartesianChartContext } from '../CartesianChart/context';
 import {
   BEACON_RADIUS,
   BEACON_STROKE_WIDTH,
-  LABEL_OFFSET_Y,
   LINE_GRADIENT_EDGE_OPACITY,
   OVERLAY_LINE_INSET,
   OVERLAY_OFFSET,
   OVERLAY_OPACITY,
 } from './constants';
 import { useScrubberContext } from './context';
+import { DefaultScrubberTooltip } from './DefaultScrubberTooltip/DefaultScrubberTooltip';
 import type { ScrubberProps } from './types';
 import { resolvePixelX, resolvePixelY } from './utils';
 
 /**
  * Renders the scrubber visuals: vertical reference line, future-data overlay
- * rect, per-series beacon dots, and an optional formatted label above the line.
+ * rect, per-series beacon dots, optional label above the line, and an optional
+ * tooltip when {@link ScrubberProps.tooltip} is set, using {@link DefaultScrubberTooltip}.
  *
  * Must be used as a child of `LineChart` (or `CartesianChart`) with
  * `enableScrubbing` enabled. Renders nothing when no scrubber position is active.
@@ -38,12 +38,23 @@ import { resolvePixelX, resolvePixelY } from './utils';
  *   <Scrubber label={(i) => data[i].date} />
  * </LineChart>
  * ```
+ *
+ * @example Tooltip
+ * ```tsx
+ * <Scrubber
+ *   tooltip={(i) => ({
+ *     title: `${counts[i]} Transactions`,
+ *     items: [{ label: 'Index', value: String(i) }],
+ *     minWidth: 160,
+ *   })}
+ * />
+ * ```
  */
 export function Scrubber({
-  label,
   hideLine = false,
   hideOverlay = false,
   showBeacons = false,
+  tooltip,
 }: Readonly<ScrubberProps>) {
   const lineGradientId = useId();
   const { theme } = useTheme();
@@ -76,10 +87,27 @@ export function Scrubber({
       );
   }, [scrubberPosition, showBeacons, series, seriesMap, getYScale]);
 
-  const resolvedLabel = useMemo(() => {
-    if (scrubberPosition === undefined || !label) return undefined;
-    return label(scrubberPosition);
-  }, [scrubberPosition, label]);
+  const tooltipPayload = useMemo(() => {
+    if (scrubberPosition === undefined || !tooltip) {
+      return undefined;
+    }
+
+    const content = tooltip(scrubberPosition);
+
+    if (content.items.length === 0) return undefined;
+
+    const resolvedTitle =
+      typeof content.title === 'function'
+        ? content.title(scrubberPosition)
+        : content.title;
+
+    return {
+      items: content.items,
+      resolvedTitle,
+      offset: content.offset,
+      minWidth: content.minWidth,
+    };
+  }, [scrubberPosition, tooltip]);
 
   if (scrubberPosition === undefined || pixelX === undefined) {
     return null;
@@ -102,7 +130,6 @@ export function Scrubber({
 
   const borderMutedColor = theme.colors.border.base;
   const backgroundBaseColor = theme.colors.bg.base;
-  const textBaseColor = theme.colors.text.base;
   const bgCanvasColor = theme.colors.bg.canvas;
 
   return (
@@ -156,21 +183,6 @@ export function Scrubber({
         />
       )}
 
-      {resolvedLabel !== undefined && (
-        <SvgText
-          testID='scrubber-label'
-          x={pixelX}
-          y={drawY - LABEL_OFFSET_Y}
-          textAnchor='middle'
-          fill={textBaseColor}
-          fontSize={theme.typographies.body4.fontSize}
-          fontWeight={theme.typographies.body4.fontWeight}
-          fontFamily={theme.fontFamilies.sans}
-        >
-          {resolvedLabel}
-        </SvgText>
-      )}
-
       {showBeacons &&
         beacons.map((beacon) => (
           <Circle
@@ -184,6 +196,17 @@ export function Scrubber({
             strokeWidth={BEACON_STROKE_WIDTH}
           />
         ))}
+
+      {tooltipPayload !== undefined && (
+        <DefaultScrubberTooltip
+          pixelX={pixelX}
+          drawingArea={drawingArea}
+          title={tooltipPayload.resolvedTitle}
+          items={tooltipPayload.items}
+          offset={tooltipPayload.offset}
+          minWidth={tooltipPayload.minWidth}
+        />
+      )}
     </G>
   );
 }

package/src/lib/Components/Scrubber/ScrubberProvider.tsx

@@ -5,9 +5,17 @@ import Animated, { useSharedValue } from 'react-native-reanimated';
 import { scheduleOnRN } from 'react-native-worklets';
 
 import { useCartesianChartContext } from '../CartesianChart/context';
+import { useMagneticPointsContext } from '../Point/pointContext';
 import { ScrubberContextProvider } from './context';
 import type { ScrubberProviderProps } from './types';
-import { getDataIndexFromPosition } from './utils';
+import {
+  applyMagnetisation,
+  getDataIndexFromPosition,
+  resolvePixelX,
+  buildSortedMagnets,
+} from './utils';
+
+const LONG_PRESS_MIN_DURATION_MS = 50;
 
 /**
  * Provides scrubbing interaction for a chart.
@@ -28,28 +36,60 @@ export function ScrubberProvider({
   height,
   enableScrubbing,
   onScrubberPositionChange,
+  magnetRadius = 6,
+  style,
 }: Readonly<ScrubberProviderProps>) {
   const [scrubberPosition, setScrubberPosition] = useState<
     number | undefined
   >();
-  const lastPositionRef = useRef<number | undefined>(undefined);
 
   const { getXScale, getXAxisConfig, dataLength } = useCartesianChartContext();
+  const { getMagneticPoints, version } = useMagneticPointsContext();
 
-  const isScrubbing = useSharedValue(false);
+  // All values touched by the gesture's JS-thread callback live in a single
+  // ref. Reading via `latest.current` keeps the callbacks reference-stable
+  // across data, scale, and prop updates, which in turn keeps `composed` and
+  // the gesture surface JSX stable so re-rendering the provider on each
+  // index change never tears down the GestureDetector or the View tree.
+  const sortedMagnets = useMemo(() => {
+    const magneticIndices = getMagneticPoints();
+    return buildSortedMagnets({
+      magneticIndices,
+      getPixelForIndex: (index) =>
+        resolvePixelX(index, getXScale, getXAxisConfig()),
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [version, getXScale, getXAxisConfig, getMagneticPoints]);
+
+  const latest = useRef({
+    getXScale,
+    getXAxisConfig,
+    dataLength,
+    onChange: onScrubberPositionChange,
+    lastIndex: undefined as number | undefined,
+    magnetRadius,
+    sortedMagnets,
+  });
+  latest.current.getXScale = getXScale;
+  latest.current.getXAxisConfig = getXAxisConfig;
+  latest.current.dataLength = dataLength;
+  latest.current.onChange = onScrubberPositionChange;
+  latest.current.magnetRadius = magnetRadius;
+  latest.current.sortedMagnets = sortedMagnets;
 
   const setScrubberPositionAndNotify = useCallback(
     (index: number | undefined) => {
+      const ref = latest.current;
       const clamped =
-        index === undefined || dataLength <= 0
+        index === undefined || ref.dataLength <= 0
           ? undefined
-          : Math.max(0, Math.min(index, dataLength - 1));
-      if (clamped === lastPositionRef.current) return;
-      lastPositionRef.current = clamped;
+          : Math.max(0, Math.min(index, ref.dataLength - 1));
+      if (clamped === ref.lastIndex) return;
+      ref.lastIndex = clamped;
       setScrubberPosition(clamped);
-      onScrubberPositionChange?.(clamped);
+      ref.onChange?.(clamped);
     },
-    [dataLength, onScrubberPositionChange],
+    [],
   );
 
   const handlePositionChange = useCallback(
@@ -58,22 +98,35 @@ export function ScrubberProvider({
         setScrubberPositionAndNotify(undefined);
         return;
       }
+      const ref = latest.current;
+      const scale = ref.getXScale();
+      if (!scale || ref.dataLength <= 0) return;
 
-      const scale = getXScale();
-      if (!scale || dataLength <= 0) return;
+      const xAxisConfig = ref.getXAxisConfig();
 
-      const axisConfig = getXAxisConfig();
-      const index = getDataIndexFromPosition(
+      let index = getDataIndexFromPosition(
         pixelX,
         scale,
-        axisConfig,
-        dataLength,
+        xAxisConfig,
+        ref.dataLength,
       );
+
+      if (ref.magnetRadius > 0) {
+        index = applyMagnetisation({
+          resolvedIndex: index,
+          pixelX,
+          sortedMagnets: ref.sortedMagnets,
+          magnetRadius: ref.magnetRadius,
+        });
+      }
+
       setScrubberPositionAndNotify(index);
     },
-    [getXScale, getXAxisConfig, dataLength, setScrubberPositionAndNotify],
+    [setScrubberPositionAndNotify],
   );
 
+  const isScrubbing = useSharedValue(false);
+
   const resetScrubber = useCallback((): void => {
     'worklet';
     isScrubbing.value = false;
@@ -82,7 +135,7 @@ export function ScrubberProvider({
 
   const composed = useMemo(() => {
     const longPress = Gesture.LongPress()
-      .minDuration(50)
+      .minDuration(LONG_PRESS_MIN_DURATION_MS)
       .onStart((e) => {
         'worklet';
         isScrubbing.value = true;
@@ -105,6 +158,27 @@ export function ScrubberProvider({
     return Gesture.Simultaneous(longPress, pan);
   }, [isScrubbing, handlePositionChange, resetScrubber]);
 
+  // Memoizing the surface lets React's element-identity bailout skip
+  // reconciling the View / GestureDetector / chart `children` subtree when
+  // only `scrubberPosition` changes. The Scrubber consumer still updates via
+  // context as expected.
+  const surface = useMemo(
+    () => (
+      <View style={[{ width, height }, style]}>
+        {children}
+        {enableScrubbing && (
+          <GestureDetector gesture={composed}>
+            <Animated.View
+              testID='scrubber-gesture-overlay'
+              style={StyleSheet.absoluteFill}
+            />
+          </GestureDetector>
+        )}
+      </View>
+    ),
+    [width, height, style, children, enableScrubbing, composed],
+  );
+
   const contextValue = useMemo(
     () => ({
       enableScrubbing,
@@ -116,17 +190,7 @@ export function ScrubberProvider({
 
   return (
     <ScrubberContextProvider value={contextValue}>
-      <View style={{ width, height }}>
-        {children}
-        {enableScrubbing && (
-          <GestureDetector gesture={composed}>
-            <Animated.View
-              testID='scrubber-gesture-overlay'
-              style={StyleSheet.absoluteFill}
-            />
-          </GestureDetector>
-        )}
-      </View>
+      {surface}
     </ScrubberContextProvider>
   );
 }

package/src/lib/Components/Scrubber/index.ts

@@ -1,3 +1,12 @@
 export { Scrubber } from './Scrubber';
 export { useScrubberContext } from './context';
-export type { ScrubberProps, ScrubberContextValue } from './types';
+
+export type {
+  ChartTooltipItemData,
+  ChartTooltipItemProps,
+  ScrubberContextValue,
+  ScrubberProps,
+  ScrubberTooltipContent,
+  ScrubberTooltipProps,
+  SvgBBoxElement,
+} from './types';

package/src/lib/Components/Scrubber/types.ts

@@ -1,4 +1,7 @@
 import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { DrawingArea } from '../../utils/types';
 
 export type ScrubberContextValue = {
   /**
@@ -33,14 +36,123 @@ export type ScrubberProviderProps = {
    * Optional external callback fired whenever the scrubber position changes.
    */
   onScrubberPositionChange?: (index: number | undefined) => void;
+  /**
+   * Pixel radius within which the scrubber magnetically snaps to registered
+   * magnetic points. Set to `0` to disable magnetisation.
+   * @default 6
+   */
+  magnetRadius?: number;
+  /**
+   * Optional style applied to the wrapping `View` that holds the chart and the
+   * gesture overlay.Used to offset the(enlarged) SVG group so its drawing area
+   * aligns with the container footprint.
+   */
+  style?: StyleProp<ViewStyle>;
 };
 
-export type ScrubberProps = {
+export type ChartTooltipItemData = {
+  /**
+   * Label displayed on the left side of the row.
+   */
+  label: string | number;
+  /**
+   * Value displayed on the right side of the row.
+   */
+  value: string | number;
+};
+
+export type ChartTooltipItemProps = ChartTooltipItemData & {
+  /**
+   * X position in SVG coordinate space.
+   * @default 0
+   */
+  x?: number;
+  /**
+   * Y midline position in SVG coordinate space.
+   * @default 0
+   */
+  y?: number;
+  /**
+   * Width allocated to this row, used to right-align the value text.
+   */
+  width: number;
+  /**
+   * Optional callback ref forwarded to the label `<Text>` element.
+   * Useful to measure the label's natural width via `getBBox` for auto-fit layouts.
+   */
+  labelRef?: (el: SvgBBoxElement | null) => void;
+  /**
+   * Optional callback ref forwarded to the value `<Text>` element.
+   * Useful to measure the value's natural width via `getBBox` for auto-fit layouts.
+   */
+  valueRef?: (el: SvgBBoxElement | null) => void;
+};
+
+/**
+ * Minimal interface for an SVG element that supports `getBBox`.
+ * Handles both react-native-svg (returns `Rect | undefined`) and web DOM SVG
+ * (returns `DOMRect` synchronously or a Promise on native bridge).
+ */
+export type SvgBBoxElement = {
+  getBBox: () =>
+    | { width: number }
+    | undefined
+    | Promise<{ width: number } | undefined>;
+};
+
+export type ScrubberTooltipLayoutProps = {
   /**
-   * Formats a label string shown above the reference line for a given data index.
-   * When omitted, no label is rendered.
+   * Horizontal gap in pixels between the scrubber line and the tooltip box.
+   * @default 10
    */
-  label?: (dataIndex: number) => string;
+  offset?: number;
+  /**
+   * Minimum width in pixels. The tooltip auto-fits to the rendered content
+   * but never collapses below this floor; raise it to avoid jitter when
+   * value length changes between indices.
+   * @default 80
+   */
+  minWidth?: number;
+};
+
+export type ScrubberTooltipProps = ScrubberTooltipLayoutProps & {
+  /**
+   * Horizontal pixel position of the scrubber line within the SVG coordinate
+   * space. Used to place the tooltip left or right of the line.
+   */
+  pixelX: number;
+  /**
+   * Bounding box of the chart's drawing area (x, y, width, height). Used to
+   * constrain the tooltip so it never overflows the chart boundaries.
+   */
+  drawingArea: DrawingArea;
+  /**
+   * Optional title displayed at the top of the tooltip. Omit to render
+   * the tooltip without a title row.
+   */
+  title?: string | number;
+  /**
+   * List of label/value pairs rendered as rows inside the tooltip body.
+   */
+  items: ChartTooltipItemData[];
+};
+
+/**
+ * Return value of the `tooltip` callback on {@link ScrubberProps}.
+ */
+export type ScrubberTooltipContent = ScrubberTooltipLayoutProps & {
+  /**
+   * Optional header. Static value or callback per data index.
+   * A callback may return `undefined` to suppress the title.
+   */
+  title?: string | number | ((index: number) => string | number | undefined);
+  /**
+   * Tooltip rows for this index. Return an empty array to hide the tooltip.
+   */
+  items: ChartTooltipItemData[];
+};
+
+export type ScrubberProps = {
   /**
    * Hides the vertical reference line.
    * @default false
@@ -56,4 +168,10 @@ export type ScrubberProps = {
    * @default false
    */
   showBeacons?: boolean;
+  /**
+   * Produces tooltip content for the active data index. When set, {@link DefaultScrubberTooltip}
+   * is rendered. Optional `offset` and `minWidth` on the returned object tune layout.
+   * Return `{ items: [] }` to hide the tooltip at an index.
+   */
+  tooltip?: (dataIndex: number) => ScrubberTooltipContent;
 };

package/src/lib/Components/Scrubber/utils.test.ts

@@ -5,10 +5,14 @@ import {
   getNumericScale,
 } from '../../utils/scales/scales';
 import {
+  applyMagnetisation,
+  buildSortedMagnets,
   getDataIndexFromPosition,
+  nearestIndex,
   resolvePixelX,
   resolvePixelY,
 } from './utils';
+import type { MagnetEntry } from './utils';
 
 describe('getDataIndexFromPosition', () => {
   describe('with a categorical (band) scale', () => {
@@ -170,3 +174,149 @@ describe('resolvePixelY', () => {
     expect(result).toBe(scale(50));
   });
 });
+
+describe('buildSortedMagnets', () => {
+  it('returns an empty array when the set is empty', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set(),
+      getPixelForIndex: () => 0,
+    });
+    expect(result).toEqual([]);
+  });
+
+  it('returns entries sorted by pixelX', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set([3, 1, 2]),
+      getPixelForIndex: (i) => i * 50,
+    });
+    expect(result).toEqual([
+      { index: 1, pixelX: 50 },
+      { index: 2, pixelX: 100 },
+      { index: 3, pixelX: 150 },
+    ]);
+  });
+
+  it('filters out indices where getPixelForIndex returns undefined', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set([0, 1, 2]),
+      getPixelForIndex: (i) => (i === 1 ? undefined : i * 100),
+    });
+    expect(result).toEqual([
+      { index: 0, pixelX: 0 },
+      { index: 2, pixelX: 200 },
+    ]);
+  });
+
+  it('returns an empty array when all indices resolve to undefined', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set([0, 1]),
+      getPixelForIndex: () => undefined,
+    });
+    expect(result).toEqual([]);
+  });
+});
+
+describe('nearestIndex', () => {
+  const magnets = (...pixelXs: number[]): MagnetEntry[] =>
+    pixelXs.map((px, i) => ({ index: i, pixelX: px }));
+
+  it('returns -1 for an empty array', () => {
+    expect(nearestIndex([], 100)).toBe(-1);
+  });
+
+  it('returns 0 for a single-element array', () => {
+    expect(nearestIndex(magnets(200), 100)).toBe(0);
+  });
+
+  it('returns the index of the exact match', () => {
+    expect(nearestIndex(magnets(100, 200, 300), 200)).toBe(1);
+  });
+
+  it('returns the closer index when target is between two values', () => {
+    expect(nearestIndex(magnets(100, 200), 160)).toBe(1);
+    expect(nearestIndex(magnets(100, 200), 140)).toBe(0);
+  });
+
+  it('favors the left index when equidistant', () => {
+    expect(nearestIndex(magnets(100, 200), 150)).toBe(0);
+  });
+
+  it('returns the last index when target is beyond all values', () => {
+    expect(nearestIndex(magnets(100, 200), 500)).toBe(1);
+  });
+
+  it('returns the first index when target is before all values', () => {
+    expect(nearestIndex(magnets(100, 200), 0)).toBe(0);
+  });
+});
+
+describe('applyMagnetisation', () => {
+  const toMagnets = (...indices: number[]): MagnetEntry[] =>
+    indices.map((i) => ({ index: i, pixelX: i * 100 }));
+
+  it('returns resolvedIndex when sortedMagnets is empty', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 200,
+        sortedMagnets: [],
+        magnetRadius: 30,
+      }),
+    ).toBe(2);
+  });
+
+  it('returns resolvedIndex when magnetRadius is 0', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 1,
+        pixelX: 200,
+        sortedMagnets: toMagnets(2),
+        magnetRadius: 0,
+      }),
+    ).toBe(1);
+  });
+
+  it('returns resolvedIndex when nearest magnet is outside radius', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 200,
+        sortedMagnets: toMagnets(0, 4),
+        magnetRadius: 30,
+      }),
+    ).toBe(2);
+  });
+
+  it('snaps to nearest magnet when within radius', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 280,
+        sortedMagnets: toMagnets(3),
+        magnetRadius: 30,
+      }),
+    ).toBe(3);
+  });
+
+  it('snaps at the exact boundary of magnetRadius', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 270,
+        sortedMagnets: toMagnets(3),
+        magnetRadius: 30,
+      }),
+    ).toBe(3);
+  });
+
+  it('does not snap when distance exceeds magnetRadius by 1', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 269,
+        sortedMagnets: toMagnets(3),
+        magnetRadius: 30,
+      }),
+    ).toBe(2);
+  });
+});